writehuman 0.0.1__tar.gz → 0.1.0__tar.gz

writehuman-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: writehuman
+Version: 0.1.0
+Summary: Official WriteHuman API client for Python: humanize AI text, detect AI authorship, read usage.
+License: MIT
+Project-URL: Homepage, https://writehuman.ai/api/docs
+Project-URL: Documentation, https://writehuman.ai/api/docs
+Project-URL: Source, https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python
+Project-URL: Changelog, https://github.com/WriteHuman-ai/rephrase-api/blob/main/sdk/python/CHANGELOG.md
+Keywords: writehuman,humanize,ai-detection,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+
+# writehuman
+
+Official WriteHuman API client for Python. Humanize AI-written text, score text for AI
+authorship, and read your usage, with typed errors and a retry policy that follows the
+API's own `Retry-After` and never resends a billed request.
+
+```
+pip install writehuman
+```
+
+```python
+from writehuman import WriteHuman, InsufficientBalanceError, RateLimitError
+
+wh = WriteHuman("wh_live_your_api_key_here")
+
+out = wh.humanize("Artificial intelligence has transformed numerous industries over the past decade.",
+                  tone="professional")
+print(out["results"][0])
+print(out["words_remaining"]["total"], "words left")
+
+score = wh.detect("Your text to check here.", include_sentences=True)
+print(score["ai_probability"], score["predicted_class"])
+
+print(wh.usage())
+```
+
+Async, same methods:
+
+```python
+from writehuman import AsyncWriteHuman
+
+async with AsyncWriteHuman("wh_live_...") as wh:
+    out = await wh.humanize("...")
+```
+
+## Errors
+
+Every failure raises a subclass of `WriteHumanError` with `code` (the API's stable error
+code), `status`, `retry_after` (seconds, when the API sent one) and, on
+`InsufficientBalanceError`, `words_remaining`.
+
+| exception | API `code` |
+|---|---|
+| `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
+| `NoSubscriptionError` | `no_subscription` |
+| `InsufficientBalanceError` | `insufficient_balance` |
+| `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
+| `ModerationError` | `moderation_blocked` |
+| `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |
+| `ServiceUnavailableError` | `at_capacity`, `billing_unavailable`, `detector_unavailable` |
+| `ServerTimeoutError` | `timeout` (the API's 504: nothing charged) |
+| `ProcessingError` | `processing_failed`, `no_results`, `safety_limit` |
+| `BillingError` | `billing_failed` (some words may have been charged; check `usage()`) |
+| `APIError` | any code this version does not know (`code` is preserved) |
+| `ProtocolError`, `ClientTimeoutError`, `ConnectionError` | no API body |
+
+```python
+try:
+    wh.humanize(text)
+except InsufficientBalanceError as e:
+    print("out of words:", e.words_remaining)
+except RateLimitError as e:
+    print("slow down; the API asked for", e.retry_after, "seconds")
+```
+
+## Retries and timeouts
+
+- `429`, `503` and `504` are retried after exactly the `Retry-After` the API sends, up to
+  `max_retries` (default 2). A `Retry-After` above `max_retry_after` (default 60 s, for
+  example an authentication lockout) is not slept through: the error is raised at once with
+  `retry_after` set. A missing `Retry-After` waits `fallback_retry_after` (default 2 s).
+- Nothing else is retried. `humanize` and `detect` are billed and non-idempotent, so a client
+  timeout, a dropped connection, or a 429/503/504 that did not come from the API (a load
+  balancer or proxy answering without the API's error body) raises immediately rather than
+  risking a second charge. `usage` is read-only and may retry those.
+- Timeouts are total deadlines through the whole response, not per-read limits (`AsyncWriteHuman`
+  enforces them exactly; `WriteHuman` checks after every chunk of the body, so it can overrun
+  by at most one network read). `timeout=` sets all operations (float) or per operation
+  (`{"humanize": 120, "detect": 30, "usage": 15}`, the defaults); `connect_timeout` defaults
+  to 10 s. Every method takes a per-call `timeout=`.
+
+```python
+wh = WriteHuman(key, timeout={"humanize": 60}, max_retries=3)
+```
+
+## Types
+
+`HumanizeResponse`, `DetectResponse`, `UsageResponse`, `WordsRemaining` and `ErrorCode`
+are generated from the API's OpenAPI document and exported for type checkers. The package
+ships `py.typed`.
+
+This client passes the WriteHuman SDK conformance suite (`sdk/conformance` in the API
+repository), as does the TypeScript client; both implement the same documented policy.

writehuman-0.1.0/README.md

@@ -0,0 +1,93 @@
+# writehuman
+
+Official WriteHuman API client for Python. Humanize AI-written text, score text for AI
+authorship, and read your usage, with typed errors and a retry policy that follows the
+API's own `Retry-After` and never resends a billed request.
+
+```
+pip install writehuman
+```
+
+```python
+from writehuman import WriteHuman, InsufficientBalanceError, RateLimitError
+
+wh = WriteHuman("wh_live_your_api_key_here")
+
+out = wh.humanize("Artificial intelligence has transformed numerous industries over the past decade.",
+                  tone="professional")
+print(out["results"][0])
+print(out["words_remaining"]["total"], "words left")
+
+score = wh.detect("Your text to check here.", include_sentences=True)
+print(score["ai_probability"], score["predicted_class"])
+
+print(wh.usage())
+```
+
+Async, same methods:
+
+```python
+from writehuman import AsyncWriteHuman
+
+async with AsyncWriteHuman("wh_live_...") as wh:
+    out = await wh.humanize("...")
+```
+
+## Errors
+
+Every failure raises a subclass of `WriteHumanError` with `code` (the API's stable error
+code), `status`, `retry_after` (seconds, when the API sent one) and, on
+`InsufficientBalanceError`, `words_remaining`.
+
+| exception | API `code` |
+|---|---|
+| `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
+| `NoSubscriptionError` | `no_subscription` |
+| `InsufficientBalanceError` | `insufficient_balance` |
+| `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
+| `ModerationError` | `moderation_blocked` |
+| `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |
+| `ServiceUnavailableError` | `at_capacity`, `billing_unavailable`, `detector_unavailable` |
+| `ServerTimeoutError` | `timeout` (the API's 504: nothing charged) |
+| `ProcessingError` | `processing_failed`, `no_results`, `safety_limit` |
+| `BillingError` | `billing_failed` (some words may have been charged; check `usage()`) |
+| `APIError` | any code this version does not know (`code` is preserved) |
+| `ProtocolError`, `ClientTimeoutError`, `ConnectionError` | no API body |
+
+```python
+try:
+    wh.humanize(text)
+except InsufficientBalanceError as e:
+    print("out of words:", e.words_remaining)
+except RateLimitError as e:
+    print("slow down; the API asked for", e.retry_after, "seconds")
+```
+
+## Retries and timeouts
+
+- `429`, `503` and `504` are retried after exactly the `Retry-After` the API sends, up to
+  `max_retries` (default 2). A `Retry-After` above `max_retry_after` (default 60 s, for
+  example an authentication lockout) is not slept through: the error is raised at once with
+  `retry_after` set. A missing `Retry-After` waits `fallback_retry_after` (default 2 s).
+- Nothing else is retried. `humanize` and `detect` are billed and non-idempotent, so a client
+  timeout, a dropped connection, or a 429/503/504 that did not come from the API (a load
+  balancer or proxy answering without the API's error body) raises immediately rather than
+  risking a second charge. `usage` is read-only and may retry those.
+- Timeouts are total deadlines through the whole response, not per-read limits (`AsyncWriteHuman`
+  enforces them exactly; `WriteHuman` checks after every chunk of the body, so it can overrun
+  by at most one network read). `timeout=` sets all operations (float) or per operation
+  (`{"humanize": 120, "detect": 30, "usage": 15}`, the defaults); `connect_timeout` defaults
+  to 10 s. Every method takes a per-call `timeout=`.
+
+```python
+wh = WriteHuman(key, timeout={"humanize": 60}, max_retries=3)
+```
+
+## Types
+
+`HumanizeResponse`, `DetectResponse`, `UsageResponse`, `WordsRemaining` and `ErrorCode`
+are generated from the API's OpenAPI document and exported for type checkers. The package
+ships `py.typed`.
+
+This client passes the WriteHuman SDK conformance suite (`sdk/conformance` in the API
+repository), as does the TypeScript client; both implement the same documented policy.

writehuman-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "writehuman"
+version = "0.1.0"
+description = "Official WriteHuman API client for Python: humanize AI text, detect AI authorship, read usage."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25,<1"]
+keywords = ["writehuman", "humanize", "ai-detection", "api-client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://writehuman.ai/api/docs"
+Documentation = "https://writehuman.ai/api/docs"
+Source = "https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python"
+Changelog = "https://github.com/WriteHuman-ai/rephrase-api/blob/main/sdk/python/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+writehuman = ["py.typed"]

writehuman-0.1.0/src/writehuman/__init__.py

@@ -0,0 +1,47 @@
+"""Official WriteHuman API client for Python.
+
+    from writehuman import WriteHuman
+    wh = WriteHuman("wh_live_...")
+    out = wh.humanize("Artificial intelligence has transformed numerous industries ...")
+    print(out["results"][0])
+
+Docs: https://writehuman.ai/api/docs. Contract: https://api.writehuman.ai/openapi.json.
+"""
+
+__version__ = "0.1.0"
+
+from .client import DEFAULT_BASE_URL, USER_AGENT, AsyncWriteHuman, WriteHuman  # noqa: E402
+from .errors import (  # noqa: E402
+    APIError,
+    AuthenticationError,
+    BillingError,
+    ClientTimeoutError,
+    ConnectionError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    ModerationError,
+    NoSubscriptionError,
+    ProcessingError,
+    ProtocolError,
+    RateLimitError,
+    ServerTimeoutError,
+    ServiceUnavailableError,
+    WriteHumanError,
+)
+from .types import (  # noqa: E402
+    API_VERSION,
+    DetectResponse,
+    ErrorCode,
+    HumanizeResponse,
+    UsageResponse,
+    WordsRemaining,
+)
+
+__all__ = [
+    "__version__", "API_VERSION", "DEFAULT_BASE_URL", "USER_AGENT",
+    "WriteHuman", "AsyncWriteHuman",
+    "WriteHumanError", "APIError", "AuthenticationError", "NoSubscriptionError", "InsufficientBalanceError",
+    "InvalidRequestError", "ModerationError", "RateLimitError", "ServiceUnavailableError", "ServerTimeoutError",
+    "ProcessingError", "BillingError", "ProtocolError", "ClientTimeoutError", "ConnectionError",
+    "HumanizeResponse", "DetectResponse", "UsageResponse", "WordsRemaining", "ErrorCode",
+]

writehuman-0.1.0/src/writehuman/_policy.py

@@ -0,0 +1,83 @@
+"""The request/retry policy shared by the sync and async clients. Pure functions, no I/O,
+so both clients are thin loops around it and the behaviour is identical. The policy is the
+one sdk/conformance/README.md specifies and the conformance scenarios enforce."""
+from typing import Any, Dict, Optional, Tuple
+
+from .errors import WriteHumanError, error_from_body
+
+RETRYABLE_STATUSES = frozenset({429, 503, 504})
+
+# Total timeouts per operation, in seconds: the 30-day p99 of successful calls with room,
+# under the API's own 170 s humanize deadline.
+DEFAULT_TIMEOUTS: Dict[str, float] = {"humanize": 120.0, "detect": 30.0, "usage": 15.0}
+DEFAULT_CONNECT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_MAX_RETRY_AFTER = 60.0
+DEFAULT_FALLBACK_RETRY_AFTER = 2.0
+
+OPERATIONS = {
+    # name: (method, path, idempotent)
+    "humanize": ("POST", "/v1/humanize", False),
+    "detect": ("POST", "/v1/detect", False),
+    "usage": ("GET", "/v1/usage", True),
+}
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+class Policy:
+    def __init__(self, *, max_retries: int = DEFAULT_MAX_RETRIES, max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
+                 fallback_retry_after: float = DEFAULT_FALLBACK_RETRY_AFTER):
+        self.max_retries = max(0, int(max_retries))
+        self.max_retry_after = float(max_retry_after)
+        self.fallback_retry_after = float(fallback_retry_after)
+
+    def wait_after_response(self, status: int, retry_after: Optional[float], attempt: int, *,
+                            from_api: bool = True, idempotent: bool = False) -> Optional[float]:
+        """Seconds to sleep before retrying a non-2xx response, or None to raise now.
+        Only 429/503/504 are retried, and only when the API itself answered (its error body):
+        the contract guarantees those left nothing charged. The same status from a load
+        balancer or proxy carries no such guarantee (a balancer 504 can follow a request the
+        server went on to finish and bill), so it is treated like a transport error."""
+        if status not in RETRYABLE_STATUSES:
+            return None
+        if not from_api:
+            return self.wait_after_transport_error(idempotent, attempt)
+        if attempt >= self.max_retries:
+            return None
+        if retry_after is None:
+            return self.fallback_retry_after
+        if retry_after > self.max_retry_after:
+            return None  # a 15-minute lockout is for the caller to decide about, not to sleep through
+        return retry_after
+
+    def wait_after_transport_error(self, idempotent: bool, attempt: int) -> Optional[float]:
+        """A timeout or dropped connection: retried only for the read-only usage call. A
+        billed POST may have been processed, so it is never resent automatically."""
+        if not idempotent or attempt >= self.max_retries:
+            return None
+        return self.fallback_retry_after
+
+
+def interpret(status: int, headers: Any, body_text: str) -> Tuple[Optional[dict], Optional[WriteHumanError], Optional[float]]:
+    """Turn a response into (data, None, retry_after) on success or (None, error, retry_after)."""
+    import json
+
+    retry_after = parse_retry_after(headers.get("Retry-After") if hasattr(headers, "get") else None)
+    try:
+        data = json.loads(body_text) if body_text else None
+    except ValueError:
+        data = None
+    if 200 <= status < 300:
+        if isinstance(data, dict):
+            return data, None, retry_after
+        from .errors import ProtocolError
+        return None, ProtocolError(f"HTTP {status} with a body that is not JSON", status=status), retry_after
+    return None, error_from_body(status, data, retry_after), retry_after

writehuman-0.1.0/src/writehuman/client.py

@@ -0,0 +1,232 @@
+"""Sync and async clients for the WriteHuman API.
+
+    from writehuman import WriteHuman
+    wh = WriteHuman("wh_live_...")
+    out = wh.humanize("Artificial intelligence has transformed ...", tone="professional")
+    print(out["results"][0], out["words_remaining"]["total"])
+
+    from writehuman import AsyncWriteHuman
+    async with AsyncWriteHuman("wh_live_...") as wh:
+        score = await wh.detect("...", include_sentences=True)
+
+Both follow the policy in sdk/conformance/README.md and pass the same conformance suite.
+"""
+import asyncio
+import time
+from typing import Any, Dict, Optional, Tuple, Union
+
+import httpx
+
+from . import __version__
+from ._policy import (
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_FALLBACK_RETRY_AFTER,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_RETRY_AFTER,
+    DEFAULT_TIMEOUTS,
+    OPERATIONS,
+    Policy,
+    interpret,
+)
+from .errors import ClientTimeoutError, ConnectionError, ProtocolError, WriteHumanError
+from .types import DetectResponse, HumanizeResponse, UsageResponse
+
+DEFAULT_BASE_URL = "https://api.writehuman.ai"
+USER_AGENT = f"writehuman-python/{__version__}"
+
+Timeouts = Union[float, Dict[str, float], None]
+
+
+def _timeouts(timeout: Timeouts) -> Dict[str, float]:
+    if timeout is None:
+        return dict(DEFAULT_TIMEOUTS)
+    if isinstance(timeout, (int, float)):
+        return {k: float(timeout) for k in DEFAULT_TIMEOUTS}
+    return {**DEFAULT_TIMEOUTS, **{k: float(v) for k, v in timeout.items()}}
+
+
+class _Base:
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: Timeouts = None,
+                 connect_timeout: float = DEFAULT_CONNECT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES,
+                 max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
+                 fallback_retry_after: float = DEFAULT_FALLBACK_RETRY_AFTER):
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeouts = _timeouts(timeout)
+        self.connect_timeout = float(connect_timeout)
+        self.policy = Policy(max_retries=max_retries, max_retry_after=max_retry_after,
+                             fallback_retry_after=fallback_retry_after)
+
+    def _headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}", "User-Agent": USER_AGENT, "Accept": "application/json"}
+
+    def _total(self, operation: str, override: Optional[float]) -> float:
+        return float(override) if override is not None else self.timeouts[operation]
+
+    def _httpx_timeout(self, operation: str, override: Optional[float]) -> httpx.Timeout:
+        total = self._total(operation, override)
+        return httpx.Timeout(total, connect=min(self.connect_timeout, total))
+
+    @staticmethod
+    def _humanize_body(text: str, tone: Optional[str], language: Optional[str]) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"text": text}
+        if tone is not None:
+            body["tone"] = tone
+        if language is not None:
+            body["language"] = language
+        return body
+
+    @staticmethod
+    def _detect_body(text: str, language: Optional[str], include_sentences: bool) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"text": text, "include_sentences": bool(include_sentences)}
+        if language is not None:
+            body["language"] = language
+        return body
+
+
+class WriteHuman(_Base):
+    """Synchronous client. Thread-safe for concurrent calls (httpx.Client is)."""
+
+    def __init__(self, api_key: str, *, http_client: Optional[httpx.Client] = None, **options: Any):
+        super().__init__(api_key, **options)
+        self._client = http_client or httpx.Client()
+        self._owns_client = http_client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "WriteHuman":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def humanize(self, text: str, *, tone: Optional[str] = None, language: Optional[str] = None,
+                 timeout: Optional[float] = None) -> HumanizeResponse:
+        return self._call("humanize", self._humanize_body(text, tone, language), timeout)  # type: ignore[return-value]
+
+    def detect(self, text: str, *, language: Optional[str] = None, include_sentences: bool = False,
+               timeout: Optional[float] = None) -> DetectResponse:
+        return self._call("detect", self._detect_body(text, language, include_sentences), timeout)  # type: ignore[return-value]
+
+    def usage(self, *, timeout: Optional[float] = None) -> UsageResponse:
+        return self._call("usage", None, timeout)  # type: ignore[return-value]
+
+    def _call(self, operation: str, body: Optional[dict], timeout: Optional[float]) -> dict:
+        method, path, idempotent = OPERATIONS[operation]
+        url = self.base_url + path
+        attempt = 0
+        while True:
+            try:
+                status, headers, text = self._send(method, url, body, operation, timeout)
+            except httpx.TimeoutException as exc:
+                wait = self.policy.wait_after_transport_error(idempotent, attempt)
+                if wait is None:
+                    raise ClientTimeoutError(f"{operation}: no response within the client timeout") from exc
+                attempt += 1
+                time.sleep(wait)
+                continue
+            except httpx.TransportError as exc:
+                wait = self.policy.wait_after_transport_error(idempotent, attempt)
+                if wait is None:
+                    raise ConnectionError(f"{operation}: could not reach {self.base_url}: {exc}") from exc
+                attempt += 1
+                time.sleep(wait)
+                continue
+            data, err, retry_after = interpret(status, headers, text)
+            if err is None:
+                return data  # type: ignore[return-value]
+            wait = self.policy.wait_after_response(status, retry_after, attempt,
+                                                   from_api=not isinstance(err, ProtocolError),
+                                                   idempotent=idempotent)
+            if wait is None:
+                raise err
+            attempt += 1
+            time.sleep(wait)
+
+    def _send(self, method: str, url: str, body: Optional[dict], operation: str,
+              timeout: Optional[float]) -> Tuple[int, Any, str]:
+        """One attempt. The timeout is a total deadline through the whole body: httpx's own
+        timeouts bound each read, so the body is streamed and the elapsed time is checked
+        after every chunk; a response can overrun the deadline by at most one network read."""
+        deadline = time.monotonic() + self._total(operation, timeout)
+        with self._client.stream(method, url, headers=self._headers(), json=body,
+                                 timeout=self._httpx_timeout(operation, timeout)) as resp:
+            chunks = []
+            for chunk in resp.iter_bytes():
+                chunks.append(chunk)
+                if time.monotonic() > deadline:
+                    raise httpx.ReadTimeout("total client timeout exceeded while reading the response")
+            return resp.status_code, resp.headers, b"".join(chunks).decode(resp.encoding or "utf-8", "replace")
+
+
+class AsyncWriteHuman(_Base):
+    """Asynchronous client, same policy and same results as WriteHuman."""
+
+    def __init__(self, api_key: str, *, http_client: Optional[httpx.AsyncClient] = None, **options: Any):
+        super().__init__(api_key, **options)
+        self._client = http_client or httpx.AsyncClient()
+        self._owns_client = http_client is None
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncWriteHuman":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def humanize(self, text: str, *, tone: Optional[str] = None, language: Optional[str] = None,
+                       timeout: Optional[float] = None) -> HumanizeResponse:
+        return await self._call("humanize", self._humanize_body(text, tone, language), timeout)  # type: ignore[return-value]
+
+    async def detect(self, text: str, *, language: Optional[str] = None, include_sentences: bool = False,
+                     timeout: Optional[float] = None) -> DetectResponse:
+        return await self._call("detect", self._detect_body(text, language, include_sentences), timeout)  # type: ignore[return-value]
+
+    async def usage(self, *, timeout: Optional[float] = None) -> UsageResponse:
+        return await self._call("usage", None, timeout)  # type: ignore[return-value]
+
+    async def _call(self, operation: str, body: Optional[dict], timeout: Optional[float]) -> dict:
+        method, path, idempotent = OPERATIONS[operation]
+        url = self.base_url + path
+        attempt = 0
+        while True:
+            try:
+                # total deadline through the whole body (httpx's own timeouts bound each read)
+                resp = await asyncio.wait_for(
+                    self._client.request(method, url, headers=self._headers(), json=body,
+                                         timeout=self._httpx_timeout(operation, timeout)),
+                    timeout=self._total(operation, timeout))
+            except (httpx.TimeoutException, asyncio.TimeoutError) as exc:
+                wait = self.policy.wait_after_transport_error(idempotent, attempt)
+                if wait is None:
+                    raise ClientTimeoutError(f"{operation}: no response within the client timeout") from exc
+                attempt += 1
+                await asyncio.sleep(wait)
+                continue
+            except httpx.TransportError as exc:
+                wait = self.policy.wait_after_transport_error(idempotent, attempt)
+                if wait is None:
+                    raise ConnectionError(f"{operation}: could not reach {self.base_url}: {exc}") from exc
+                attempt += 1
+                await asyncio.sleep(wait)
+                continue
+            data, err, retry_after = interpret(resp.status_code, resp.headers, resp.text)
+            if err is None:
+                return data  # type: ignore[return-value]
+            wait = self.policy.wait_after_response(resp.status_code, retry_after, attempt,
+                                                   from_api=not isinstance(err, ProtocolError),
+                                                   idempotent=idempotent)
+            if wait is None:
+                raise err
+            attempt += 1
+            await asyncio.sleep(wait)
+
+
+__all__ = ["WriteHuman", "AsyncWriteHuman", "WriteHumanError", "DEFAULT_BASE_URL", "USER_AGENT"]

writehuman-0.1.0/src/writehuman/errors.py

@@ -0,0 +1,134 @@
+"""Typed errors. Every error carries the attributes the conformance suite reads:
+
+    kind             abstract type (see sdk/conformance/README.md); one class per kind
+    code             the API's `code`, or None when there was no API body
+    status           HTTP status, or None for client-side failures
+    retry_after      seconds the API asked us to wait (from the last response), or None
+    words_remaining  on InsufficientBalanceError: {"included", "topup", "total"}
+"""
+from typing import Optional
+
+from .types import ErrorCode, WordsRemaining
+
+
+class WriteHumanError(Exception):
+    """Base of every error this library raises."""
+
+    kind = "api"
+
+    def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None,
+                 retry_after: Optional[float] = None, words_remaining: Optional[WordsRemaining] = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+        self.words_remaining = words_remaining
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r}, status={self.status}, code={self.code!r})"
+
+
+class APIError(WriteHumanError):
+    """A well-formed error whose `code` this version of the library does not know."""
+    kind = "api"
+
+
+class AuthenticationError(WriteHumanError):
+    """missing_api_key, invalid_api_key."""
+    kind = "authentication"
+
+
+class NoSubscriptionError(WriteHumanError):
+    """The key is valid but the account has no active API subscription."""
+    kind = "no_subscription"
+
+
+class InsufficientBalanceError(WriteHumanError):
+    """Out of words. `words_remaining` says what is left."""
+    kind = "insufficient_balance"
+
+
+class InvalidRequestError(WriteHumanError):
+    """invalid_request, forbidden_param, word_limit."""
+    kind = "invalid_request"
+
+
+class ModerationError(WriteHumanError):
+    """Content moderation refused the input."""
+    kind = "moderation"
+
+
+class RateLimitError(WriteHumanError):
+    """rate_limited, auth_locked_out, queue_full, queue_timeout. Retried per Retry-After."""
+    kind = "rate_limit"
+
+
+class ServiceUnavailableError(WriteHumanError):
+    """at_capacity, billing_unavailable, detector_unavailable. Retried per Retry-After."""
+    kind = "service_unavailable"
+
+
+class ServerTimeoutError(WriteHumanError):
+    """The API's own deadline (504 `timeout`): nothing charged, retried per Retry-After."""
+    kind = "server_timeout"
+
+
+class ProcessingError(WriteHumanError):
+    """processing_failed, no_results, safety_limit. Never retried."""
+    kind = "processing"
+
+
+class BillingError(WriteHumanError):
+    """billing_failed: the result was produced but the usage write failed part-way; some
+    words may have been charged. Never retried; check usage()."""
+    kind = "billing"
+
+
+class ProtocolError(WriteHumanError):
+    """The response was not the JSON the contract promises."""
+    kind = "protocol"
+
+
+class ClientTimeoutError(WriteHumanError):
+    """No response within the client timeout. Not retried on humanize/detect (billed)."""
+    kind = "client_timeout"
+
+
+class ConnectionError(WriteHumanError):  # noqa: A001 — mirrors the TypeScript name on purpose
+    """The connection failed. Not retried on humanize/detect (billed)."""
+    kind = "connection"
+
+
+KIND_BY_CODE = {
+    "missing_api_key": "authentication", "invalid_api_key": "authentication",
+    "no_subscription": "no_subscription",
+    "insufficient_balance": "insufficient_balance",
+    "invalid_request": "invalid_request", "forbidden_param": "invalid_request", "word_limit": "invalid_request",
+    "moderation_blocked": "moderation",
+    "rate_limited": "rate_limit", "auth_locked_out": "rate_limit", "queue_full": "rate_limit", "queue_timeout": "rate_limit",
+    "at_capacity": "service_unavailable", "billing_unavailable": "service_unavailable", "detector_unavailable": "service_unavailable",
+    "timeout": "server_timeout",
+    "processing_failed": "processing", "no_results": "processing", "safety_limit": "processing",
+    "billing_failed": "billing",
+}
+
+CLASS_BY_KIND = {cls.kind: cls for cls in (
+    APIError, AuthenticationError, NoSubscriptionError, InsufficientBalanceError, InvalidRequestError,
+    ModerationError, RateLimitError, ServiceUnavailableError, ServerTimeoutError, ProcessingError, BillingError,
+)}
+
+
+def error_from_body(status: int, body: object, retry_after: Optional[float]) -> WriteHumanError:
+    """Build the typed error for a non-2xx response."""
+    # The API's error body always has a string `error` and a string `code`. Anything else (an
+    # HTML page, or JSON like {"error": "Gateway timeout"} with no code) came from a load
+    # balancer or proxy, which gives no guarantee about whether the request was processed.
+    if not isinstance(body, dict) or not isinstance(body.get("error"), str) or not isinstance(body.get("code"), str):
+        return ProtocolError(f"HTTP {status} with a body that is not the API's error shape", status=status,
+                             retry_after=retry_after)
+    code: Optional[ErrorCode] = body["code"]  # type: ignore[assignment]
+    cls = CLASS_BY_KIND.get(KIND_BY_CODE.get(code or "", "api"), APIError)
+    wr = body.get("words_remaining")
+    return cls(body["error"], status=status, code=code, retry_after=retry_after,
+               words_remaining=wr if isinstance(wr, dict) else None)

writehuman-0.1.0/src/writehuman/types.py

@@ -0,0 +1,155 @@
+# GENERATED from src/openapi.json by sdk/gen_types.py. Do not edit; run the generator.
+# Contract version 1.1.
+from typing import Any, List, Literal, Optional, TypedDict
+
+API_VERSION = "v1.1"
+
+
+class _HumanizeRequestOptional(TypedDict, total=False):
+    # Optional writing tone. Omit for default style. A value outside this list is ignored.
+    tone: Optional[Literal["professional", "academic", "blog", "casual", "creative", "scientific", "technical"]]
+    # Target language (e.g. `English`, `Spanish`, `Chinese (Mandarin)`). Auto-detected if omitted.
+    language: Optional[str]
+
+
+class HumanizeRequest(_HumanizeRequestOptional):
+    # The text to humanize.
+    text: str
+
+
+class WordsRemaining(TypedDict):
+    # Words remaining in your monthly subscription allowance.
+    included: int
+    # Words remaining from purchased top-ups.
+    topup: int
+    # Total words available (included + topup).
+    total: int
+
+
+class HumanizeResponse(TypedDict):
+    # Unique identifier for this humanization request.
+    id: str
+    # Unix timestamp (milliseconds) when the request was received.
+    created: int
+    # Humanized text variations, sorted by score (best first).
+    results: List[str]
+    # Human-likeness score per result (0–1, higher = more human). `null` on Standard plans; array on Premium.
+    scores: Optional[List[Optional[float]]]
+    # Number of words billed for this request.
+    input_words: int
+    words_remaining: "WordsRemaining"
+
+
+class UsageResponse(TypedDict):
+    # Monthly word allowance for your plan.
+    included_words: int
+    # Words consumed in the current billing cycle.
+    words_used_this_cycle: int
+    # Remaining purchased top-up words.
+    topup_balance: int
+    # Your plan. Every Premium size reports `api_premium`.
+    tier: Literal["api_standard", "api_premium"]
+    # API version.
+    version: str
+
+
+class _DetectRequestOptional(TypedDict, total=False):
+    # Language of the input (e.g. `English`, `Spanish`). Auto-detected if omitted. Non-English text is translated to English before scoring.
+    language: Optional[str]
+    # Include per-sentence AI probabilities in the response.
+    include_sentences: bool
+
+
+class DetectRequest(_DetectRequestOptional):
+    # The text to score.
+    text: str
+
+
+class _DetectResponseClassProbabilitiesOptional(TypedDict, total=False):
+    ai: Optional[float]
+    human: Optional[float]
+    mixed: Optional[float]
+
+
+class DetectResponseClassProbabilities(_DetectResponseClassProbabilitiesOptional):
+    """Probabilities for each class."""
+    pass
+
+
+class DetectResponseRequestMetaDocLength(TypedDict):
+    """Length of the scored text."""
+    chars: Optional[int]
+    tokens: Optional[int]
+
+
+class DetectResponseRequestMeta(TypedDict):
+    # Length of the scored text.
+    doc_length: "DetectResponseRequestMetaDocLength"
+
+
+class DetectResponseSentencesItem(TypedDict):
+    text: Optional[str]
+    ai_prob: Optional[float]
+
+
+class _DetectResponseOptional(TypedDict, total=False):
+    # Per-sentence AI probabilities. Present only when `include_sentences` is `true`.
+    sentences: List["DetectResponseSentencesItem"]
+
+
+class DetectResponse(_DetectResponseOptional):
+    # Identifier for this detection scan.
+    scanId: Optional[str]
+    # Detector model version.
+    version: Optional[str]
+    # Detector build identifier.
+    versionID: Optional[str]
+    # Probability the text is AI-generated (`1` = AI — opposite orientation of `/v1/humanize` scores).
+    ai_probability: Optional[float]
+    # Overall label for the document.
+    predicted_class: Optional[Literal["ai", "human", "mixed"]]
+    # Probabilities for each class.
+    class_probabilities: "DetectResponseClassProbabilities"
+    request_meta: "DetectResponseRequestMeta"
+    # Detected (or supplied) language of the input.
+    language: str
+
+
+ErrorCode = Literal[
+    "invalid_request",
+    "forbidden_param",
+    "word_limit",
+    "moderation_blocked",
+    "missing_api_key",
+    "invalid_api_key",
+    "no_subscription",
+    "insufficient_balance",
+    "rate_limited",
+    "auth_locked_out",
+    "queue_full",
+    "queue_timeout",
+    "at_capacity",
+    "billing_unavailable",
+    "detector_unavailable",
+    "timeout",
+    "processing_failed",
+    "no_results",
+    "safety_limit",
+    "billing_failed",
+]
+
+
+class ErrorResponse(TypedDict):
+    # Human-readable error message.
+    error: str
+    code: "ErrorCode"
+
+
+class _ErrorResponseWithBalanceOptional(TypedDict, total=False):
+    words_remaining: "WordsRemaining"
+
+
+class ErrorResponseWithBalance(_ErrorResponseWithBalanceOptional):
+    # Human-readable error message.
+    error: str
+    code: "ErrorCode"

writehuman-0.1.0/src/writehuman.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: writehuman
+Version: 0.1.0
+Summary: Official WriteHuman API client for Python: humanize AI text, detect AI authorship, read usage.
+License: MIT
+Project-URL: Homepage, https://writehuman.ai/api/docs
+Project-URL: Documentation, https://writehuman.ai/api/docs
+Project-URL: Source, https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python
+Project-URL: Changelog, https://github.com/WriteHuman-ai/rephrase-api/blob/main/sdk/python/CHANGELOG.md
+Keywords: writehuman,humanize,ai-detection,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+
+# writehuman
+
+Official WriteHuman API client for Python. Humanize AI-written text, score text for AI
+authorship, and read your usage, with typed errors and a retry policy that follows the
+API's own `Retry-After` and never resends a billed request.
+
+```
+pip install writehuman
+```
+
+```python
+from writehuman import WriteHuman, InsufficientBalanceError, RateLimitError
+
+wh = WriteHuman("wh_live_your_api_key_here")
+
+out = wh.humanize("Artificial intelligence has transformed numerous industries over the past decade.",
+                  tone="professional")
+print(out["results"][0])
+print(out["words_remaining"]["total"], "words left")
+
+score = wh.detect("Your text to check here.", include_sentences=True)
+print(score["ai_probability"], score["predicted_class"])
+
+print(wh.usage())
+```
+
+Async, same methods:
+
+```python
+from writehuman import AsyncWriteHuman
+
+async with AsyncWriteHuman("wh_live_...") as wh:
+    out = await wh.humanize("...")
+```
+
+## Errors
+
+Every failure raises a subclass of `WriteHumanError` with `code` (the API's stable error
+code), `status`, `retry_after` (seconds, when the API sent one) and, on
+`InsufficientBalanceError`, `words_remaining`.
+
+| exception | API `code` |
+|---|---|
+| `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
+| `NoSubscriptionError` | `no_subscription` |
+| `InsufficientBalanceError` | `insufficient_balance` |
+| `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
+| `ModerationError` | `moderation_blocked` |
+| `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |
+| `ServiceUnavailableError` | `at_capacity`, `billing_unavailable`, `detector_unavailable` |
+| `ServerTimeoutError` | `timeout` (the API's 504: nothing charged) |
+| `ProcessingError` | `processing_failed`, `no_results`, `safety_limit` |
+| `BillingError` | `billing_failed` (some words may have been charged; check `usage()`) |
+| `APIError` | any code this version does not know (`code` is preserved) |
+| `ProtocolError`, `ClientTimeoutError`, `ConnectionError` | no API body |
+
+```python
+try:
+    wh.humanize(text)
+except InsufficientBalanceError as e:
+    print("out of words:", e.words_remaining)
+except RateLimitError as e:
+    print("slow down; the API asked for", e.retry_after, "seconds")
+```
+
+## Retries and timeouts
+
+- `429`, `503` and `504` are retried after exactly the `Retry-After` the API sends, up to
+  `max_retries` (default 2). A `Retry-After` above `max_retry_after` (default 60 s, for
+  example an authentication lockout) is not slept through: the error is raised at once with
+  `retry_after` set. A missing `Retry-After` waits `fallback_retry_after` (default 2 s).
+- Nothing else is retried. `humanize` and `detect` are billed and non-idempotent, so a client
+  timeout, a dropped connection, or a 429/503/504 that did not come from the API (a load
+  balancer or proxy answering without the API's error body) raises immediately rather than
+  risking a second charge. `usage` is read-only and may retry those.
+- Timeouts are total deadlines through the whole response, not per-read limits (`AsyncWriteHuman`
+  enforces them exactly; `WriteHuman` checks after every chunk of the body, so it can overrun
+  by at most one network read). `timeout=` sets all operations (float) or per operation
+  (`{"humanize": 120, "detect": 30, "usage": 15}`, the defaults); `connect_timeout` defaults
+  to 10 s. Every method takes a per-call `timeout=`.
+
+```python
+wh = WriteHuman(key, timeout={"humanize": 60}, max_retries=3)
+```
+
+## Types
+
+`HumanizeResponse`, `DetectResponse`, `UsageResponse`, `WordsRemaining` and `ErrorCode`
+are generated from the API's OpenAPI document and exported for type checkers. The package
+ships `py.typed`.
+
+This client passes the WriteHuman SDK conformance suite (`sdk/conformance` in the API
+repository), as does the TypeScript client; both implement the same documented policy.

writehuman-0.1.0/src/writehuman.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/writehuman/__init__.py
+src/writehuman/_policy.py
+src/writehuman/client.py
+src/writehuman/errors.py
+src/writehuman/py.typed
+src/writehuman/types.py
+src/writehuman.egg-info/PKG-INFO
+src/writehuman.egg-info/SOURCES.txt
+src/writehuman.egg-info/dependency_links.txt
+src/writehuman.egg-info/requires.txt
+src/writehuman.egg-info/top_level.txt

writehuman-0.1.0/src/writehuman.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.25

writehuman-0.0.1/PKG-INFO

@@ -1,19 +0,0 @@
-Metadata-Version: 2.4
-Name: writehuman
-Version: 0.0.1
-Summary: Official WriteHuman API client for Python (placeholder release; the client ships in 0.1).
-License: MIT
-Project-URL: Homepage, https://writehuman.ai/api/docs
-Project-URL: Source, https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python
-Keywords: writehuman,humanize,ai-detection,api-client
-Classifier: Development Status :: 1 - Planning
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
-# writehuman
-
-Official WriteHuman API client for Python.
-
-This is a placeholder release that reserves the package name. The client ships in 0.1.
-Until then, call the REST API directly: https://writehuman.ai/api/docs

writehuman-0.0.1/README.md

@@ -1,6 +0,0 @@
-# writehuman
-
-Official WriteHuman API client for Python.
-
-This is a placeholder release that reserves the package name. The client ships in 0.1.
-Until then, call the REST API directly: https://writehuman.ai/api/docs

writehuman-0.0.1/pyproject.toml

@@ -1,20 +0,0 @@
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "writehuman"
-version = "0.0.1"
-description = "Official WriteHuman API client for Python (placeholder release; the client ships in 0.1)."
-readme = "README.md"
-license = { text = "MIT" }
-requires-python = ">=3.9"
-keywords = ["writehuman", "humanize", "ai-detection", "api-client"]
-classifiers = ["Development Status :: 1 - Planning", "Programming Language :: Python :: 3"]
-
-[project.urls]
-Homepage = "https://writehuman.ai/api/docs"
-Source = "https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python"
-
-[tool.setuptools.packages.find]
-where = ["src"]

writehuman-0.0.1/src/writehuman/__init__.py

@@ -1,3 +0,0 @@
-"""WriteHuman API client. Placeholder release; the client ships in 0.1."""
-
-__version__ = "0.0.1"

writehuman-0.0.1/src/writehuman.egg-info/PKG-INFO

@@ -1,19 +0,0 @@
-Metadata-Version: 2.4
-Name: writehuman
-Version: 0.0.1
-Summary: Official WriteHuman API client for Python (placeholder release; the client ships in 0.1).
-License: MIT
-Project-URL: Homepage, https://writehuman.ai/api/docs
-Project-URL: Source, https://github.com/WriteHuman-ai/rephrase-api/tree/main/sdk/python
-Keywords: writehuman,humanize,ai-detection,api-client
-Classifier: Development Status :: 1 - Planning
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
-# writehuman
-
-Official WriteHuman API client for Python.
-
-This is a placeholder release that reserves the package name. The client ships in 0.1.
-Until then, call the REST API directly: https://writehuman.ai/api/docs

writehuman-0.0.1/src/writehuman.egg-info/SOURCES.txt

@@ -1,7 +0,0 @@
-README.md
-pyproject.toml
-src/writehuman/__init__.py
-src/writehuman.egg-info/PKG-INFO
-src/writehuman.egg-info/SOURCES.txt
-src/writehuman.egg-info/dependency_links.txt
-src/writehuman.egg-info/top_level.txt