clavis-sinica 0.1.0__tar.gz

clavis_sinica-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clavis Sinica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clavis_sinica-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+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

clavis_sinica-0.1.0/README.md

@@ -0,0 +1,46 @@
+# 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

clavis_sinica-0.1.0/clavis_sinica/__init__.py

@@ -0,0 +1,39 @@
+"""Clavis Sinica —— 中文语义分解 API 的官方 Python 客户端。
+
+设计取舍(每一条都来自 2026-09-10 的真实实测, 不是照文档抄的):
+
+* 认证只有 `Authorization: Bearer ck-live_...` 一种。实测过 X-API-Key /
+  Authorization 裸值 / 小写变体 / 查询参数, 全部 401。
+* 请求一律用 `payload` 形态。`{"input": ...}` 那种快捷写法只能设置单字段
+  服务的主字段, 存在的唯一理由是历史兼容 —— 统一走 payload 就不必判断
+  "这个服务能不能用 input"。
+* 字段规格不硬编码, 启动时从 `/v1/chinese/services` 拉。那个接口零费用,
+  且与引擎校验用的是同一份定义。此前有接入方维护本地手抄规格表, 累计
+  出过五处错误, 根因都是"规格只存在于服务端的代码里"。
+* 429 按 `Retry-After` 退避, 5xx 指数退避, 4xx 立即抛。被限流的请求不
+  扣费, 所以重试是安全的。
+* `upstream_error` / `upstream_unavailable` 是服务端侧故障, 与调用方的
+  请求无关, 值得重试; `invalid_param` 这类改了参数再发才有意义。
+* 异步服务(decompose.lesson / decompose.wenyan_lesson)自动轮询到终态,
+  调用方不需要自己写轮询循环。
+* 响应里的 `warnings` 默认打到 logging.WARNING。顶层未知字段会被静默
+  丢弃, 这个数组是唯一提示 —— 曾有接入方在顶层发了几个月的无效参数,
+  一切正常、毫无信号。
+"""
+from .client import (
+    Clavis,
+    ClavisError,
+    ClavisAuthError,
+    ClavisParamError,
+    ClavisRateLimited,
+    ClavisUpstreamError,
+    ClavisNotFound,
+    ClavisTimeout,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Clavis", "ClavisError", "ClavisAuthError", "ClavisParamError",
+    "ClavisRateLimited", "ClavisUpstreamError", "ClavisNotFound",
+    "ClavisTimeout",
+]

clavis_sinica-0.1.0/clavis_sinica/client.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+import requests
+
+log = logging.getLogger("clavis_sinica")
+
+DEFAULT_BASE_URL = "https://clavissinica.org"
+
+
+class ClavisError(Exception):
+    """所有本客户端抛出的错误的基类。"""
+
+    def __init__(self, message, *, status_code=None, error=None, payload=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error = error
+        self.payload = payload or {}
+
+    def __str__(self):
+        base = super().__str__()
+        return "%s (HTTP %s, error=%s)" % (base, self.status_code, self.error)
+
+
+class ClavisAuthError(ClavisError):
+    """401 —— Key 缺失/格式错/前缀不对/已吊销。重试没有意义。"""
+
+
+class ClavisParamError(ClavisError):
+    """400 invalid_param —— 参数有问题。`field` 指出是哪一个。"""
+
+    @property
+    def field(self):
+        return self.payload.get("field")
+
+    @property
+    def expected(self):
+        return self.payload.get("expected")
+
+
+class ClavisNotFound(ClavisError):
+    """404 —— 接口正常, 内容不在词典里。重试没有意义。"""
+
+
+class ClavisRateLimited(ClavisError):
+    """429 —— 触发限流。被拒的请求不扣费。"""
+
+    @property
+    def retry_after(self):
+        return self.payload.get("retry_after")
+
+    @property
+    def scope(self):
+        return self.payload.get("scope")
+
+
+class ClavisUpstreamError(ClavisError):
+    """502/503 —— 服务端侧故障, 与你的请求无关。退避后重试是合理的。"""
+
+
+class ClavisTimeout(ClavisError):
+    """异步任务在给定时间内没有到达终态。任务本身可能仍在跑。"""
+
+
+_RETRYABLE_STATUS = (429, 502, 503)
+_TERMINAL_TASK_STATES = ("done", "error", "success", "completed", "failed")
+
+
+class Clavis:
+    """Clavis Sinica API 客户端。
+
+        c = Clavis("ck-live_...")
+        c.run("decompose.idiom", {"idiom": "守株待兔"})
+        c.run("decompose.lesson", {"text": "...", "title": "..."})   # 自动轮询
+
+    参数
+        api_key      形如 ck-live_ / ck-test_ 的 Key
+        base_url     默认 https://clavissinica.org
+        max_retries  429/5xx 的最大重试次数, 默认 4
+        load_catalog 构造时是否拉取服务目录, 默认 True。设 False 可以
+                     省掉一次网络往返, 但异步服务将无法自动识别,
+                     需要显式传 poll=True
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 180.0, max_retries: int = 4,
+                 session: Optional[requests.Session] = None,
+                 load_catalog: bool = True):
+        if not api_key or not api_key.startswith("ck-"):
+            # 提前拦住最常见的两种错: 传了 chinesekey.org 的 pk_live_ Key,
+            # 或者把 Stripe 的 cs_live_ 当成了 API Key。服务端也会拒,
+            # 但在这里拒能省一次往返, 而且错误信息更直白。
+            raise ValueError(
+                "api_key 必须以 ck- 开头(ck-live_ 或 ck-test_)。"
+                "chinesekey.org 的 pk_live_ Key 不能用在这里; "
+                "cs_live_ 开头的是 Stripe checkout 会话 id, 不是 API Key。")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.http = session or requests.Session()
+        self.http.headers.update({
+            "Authorization": "Bearer " + api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "clavis-sinica-python/0.1.0",
+        })
+        self._catalog: Optional[Dict[str, Any]] = None
+        self._modes: Dict[str, str] = {}
+        if load_catalog:
+            try:
+                self.refresh_catalog()
+            except ClavisError:
+                # 目录拉不到不该让构造失败 —— 调用时显式传 poll 仍然可用
+                log.warning("服务目录拉取失败, 异步服务需显式传 poll=True")
+
+    # ── 服务目录 ────────────────────────────────────────
+    def refresh_catalog(self) -> Dict[str, Any]:
+        """拉取 /v1/chinese/services。零费用, 任意有效 Key 可读。"""
+        self._catalog = self._request("GET", "/v1/chinese/services")
+        self._modes = {
+            s["service_code"]: (s.get("execution") or {}).get("mode", "sync")
+            for s in self._catalog.get("services", [])
+        }
+        return self._catalog
+
+    @property
+    def catalog(self) -> Dict[str, Any]:
+        if self._catalog is None:
+            self.refresh_catalog()
+        return self._catalog
+
+    def service_codes(self) -> List[str]:
+        return list(self._modes) or [
+            s["service_code"] for s in self.catalog.get("services", [])]
+
+    def spec(self, service_code: str) -> Dict[str, Any]:
+        """某个服务的完整字段规格 —— 权威来源, 不要在本地抄一份。"""
+        for s in self.catalog.get("services", []):
+            if s["service_code"] == service_code:
+                return s
+        raise KeyError(service_code)
+
+    # ── 调用 ────────────────────────────────────────────
+    def run(self, service_code: str, payload: Dict[str, Any],
+            idempotency_key: Optional[str] = None,
+            poll: Optional[bool] = None,
+            poll_interval: float = 5.0,
+            poll_timeout: float = 600.0) -> Dict[str, Any]:
+        """调用一个服务。
+
+        同步服务直接返回完整响应体。异步服务(submit_poll)默认自动轮询
+        到终态再返回; 传 poll=False 可以拿到 {"task_id": ...} 自己轮询。
+        """
+        body = {"service_code": service_code, "payload": payload}
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        out = self._request("POST", "/v1/chinese/run", json=body)
+
+        if poll is None:
+            poll = self._modes.get(service_code) == "submit_poll"
+        task_id = out.get("task_id")
+        if task_id and poll:
+            return self.wait_task(task_id, interval=poll_interval,
+                                  timeout=poll_timeout)
+        return out
+
+    def get_task(self, task_id: str) -> Dict[str, Any]:
+        return self._request("GET", "/v1/chinese/tasks/" + task_id)
+
+    def wait_task(self, task_id: str, interval: float = 5.0,
+                  timeout: float = 600.0) -> Dict[str, Any]:
+        deadline = time.time() + timeout
+        while True:
+            t = self.get_task(task_id)
+            if (t.get("status") or "") in _TERMINAL_TASK_STATES:
+                return t
+            if time.time() >= deadline:
+                raise ClavisTimeout(
+                    "任务 %s 在 %.0f 秒内没有到达终态(它可能仍在执行, "
+                    "可以稍后用 get_task 继续查)" % (task_id, timeout),
+                    payload={"task_id": task_id, "last_status": t.get("status")})
+            time.sleep(interval)
+
+    # ── 账户 ────────────────────────────────────────────
+    def balance(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/account/balance")
+
+    def usage(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/account/usage")
+
+    def ledger(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/account/ledger")
+
+    # ── 内部 ────────────────────────────────────────────
+    def _request(self, method: str, path: str, **kw) -> Dict[str, Any]:
+        url = self.base_url + path
+        last_exc = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = self.http.request(method, url, timeout=self.timeout, **kw)
+            except requests.RequestException as e:
+                last_exc = ClavisUpstreamError("网络请求失败: %s" % e)
+                if attempt < self.max_retries:
+                    time.sleep(min(2 ** attempt, 30))
+                    continue
+                raise last_exc
+
+            if r.status_code < 300:
+                data = r.json()
+                for w in (data.get("warnings") or []):
+                    # 顶层未知字段会被静默丢弃, 这个数组是唯一提示。
+                    log.warning("clavis warning: %s", w)
+                return data
+
+            detail, err, msg = self._parse_error(r)
+            if r.status_code in _RETRYABLE_STATUS and attempt < self.max_retries:
+                wait = self._retry_wait(r, detail, attempt)
+                log.warning("HTTP %s (%s), %.1f 秒后重试 (%d/%d)",
+                            r.status_code, err, wait, attempt + 1, self.max_retries)
+                time.sleep(wait)
+                continue
+            raise self._to_exception(r.status_code, err, msg, detail)
+        raise last_exc or ClavisError("请求失败")
+
+    @staticmethod
+    def _parse_error(r):
+        try:
+            body = r.json()
+        except Exception:
+            # nginx 直接返回的错误是 HTML(比如请求体超过 8MB 被挡在应用之外)
+            return ({}, "http_%d" % r.status_code,
+                    (r.text or "")[:200].strip())
+        detail = body.get("detail") if isinstance(body.get("detail"), dict) else body
+        return detail, detail.get("error"), detail.get("msg") or str(body)[:200]
+
+    @staticmethod
+    def _retry_wait(r, detail, attempt):
+        hdr = r.headers.get("Retry-After")
+        if hdr:
+            try:
+                return float(hdr)
+            except ValueError:
+                pass
+        if isinstance(detail, dict) and detail.get("retry_after"):
+            return float(detail["retry_after"])
+        return min(2 ** attempt, 30)
+
+    @staticmethod
+    def _to_exception(status, err, msg, detail):
+        kw = dict(status_code=status, error=err, payload=detail or {})
+        if status == 401:
+            return ClavisAuthError(msg, **kw)
+        if status == 404 or err == "not_found":
+            return ClavisNotFound(msg, **kw)
+        if status == 429 or err == "rate_limited":
+            return ClavisRateLimited(msg, **kw)
+        if status in (502, 503) or (err or "").startswith("upstream_"):
+            return ClavisUpstreamError(msg, **kw)
+        if status == 400 or err == "invalid_param":
+            return ClavisParamError(msg, **kw)
+        return ClavisError(msg, **kw)

clavis_sinica-0.1.0/clavis_sinica.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+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

clavis_sinica-0.1.0/clavis_sinica.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+clavis_sinica/__init__.py
+clavis_sinica/client.py
+clavis_sinica.egg-info/PKG-INFO
+clavis_sinica.egg-info/SOURCES.txt
+clavis_sinica.egg-info/dependency_links.txt
+clavis_sinica.egg-info/requires.txt
+clavis_sinica.egg-info/top_level.txt

clavis_sinica-0.1.0/clavis_sinica.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clavis_sinica-0.1.0/clavis_sinica.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.25
+
+[dev]
+pytest>=7.0

clavis_sinica-0.1.0/clavis_sinica.egg-info/top_level.txt

@@ -0,0 +1 @@
+clavis_sinica

clavis_sinica-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clavis-sinica"
+version = "0.1.0"
+description = "Official Python client for the Clavis Sinica API — Chinese idiom, sentence, passage, classical Chinese and lesson decomposition."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [{name = "Clavis Sinica"}]
+keywords = ["chinese", "nlp", "idiom", "classical-chinese", "hsk", "api-client"]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://clavissinica.org"
+Documentation = "https://clavissinica.org/docs"
+"API Reference" = "https://clavissinica.org/openapi.json"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["clavis_sinica*"]

clavis_sinica-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+