writehuman 0.1.0__tar.gz → 0.2.0__tar.gz

{writehuman-0.1.0 → writehuman-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: writehuman
-Version: 0.1.0
+Version: 0.2.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
@@ -44,6 +44,16 @@ print(score["ai_probability"], score["predicted_class"])
 print(wh.usage())
 ```
 
+Premium plans and above can ask for the enhanced model. On a Standard plan this raises
+`PlanRequiredError` (nothing is charged) with `upgrade_url` set; while the enhanced model is
+switched off on the API it raises `FeatureUnavailableError`, so send without `enhanced`. Every
+humanize response's `model` (`"standard"` or `"enhanced"`) says which model served it:
+
+```python
+out = wh.humanize(text, enhanced=True)
+print(out["model"])  # "enhanced"
+```
+
 Async, same methods:
 
 ```python
@@ -57,13 +67,16 @@ async with AsyncWriteHuman("wh_live_...") as wh:
 
 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`.
+`InsufficientBalanceError`, `words_remaining`; on `PlanRequiredError`, `upgrade_url`.
 
 | exception | API `code` |
 |---|---|
 | `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
 | `NoSubscriptionError` | `no_subscription` |
 | `InsufficientBalanceError` | `insufficient_balance` |
+| `ReverifyRequiredError` | `reverify_required` (403: the account owner must re-verify by email at writehuman.ai; not retried) |
+| `PlanRequiredError` | `enhanced_requires_premium` (403: `enhanced=True` on a Standard plan; `upgrade_url` says where to upgrade; nothing charged; not retried) |
+| `FeatureUnavailableError` | `enhanced_unavailable` (403: the enhanced model is switched off for everyone; send without `enhanced`; nothing charged; not retried) |
 | `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
 | `ModerationError` | `moderation_blocked` |
 | `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |

{writehuman-0.1.0 → writehuman-0.2.0}/README.md

@@ -24,6 +24,16 @@ print(score["ai_probability"], score["predicted_class"])
 print(wh.usage())
 ```
 
+Premium plans and above can ask for the enhanced model. On a Standard plan this raises
+`PlanRequiredError` (nothing is charged) with `upgrade_url` set; while the enhanced model is
+switched off on the API it raises `FeatureUnavailableError`, so send without `enhanced`. Every
+humanize response's `model` (`"standard"` or `"enhanced"`) says which model served it:
+
+```python
+out = wh.humanize(text, enhanced=True)
+print(out["model"])  # "enhanced"
+```
+
 Async, same methods:
 
 ```python
@@ -37,13 +47,16 @@ async with AsyncWriteHuman("wh_live_...") as wh:
 
 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`.
+`InsufficientBalanceError`, `words_remaining`; on `PlanRequiredError`, `upgrade_url`.
 
 | exception | API `code` |
 |---|---|
 | `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
 | `NoSubscriptionError` | `no_subscription` |
 | `InsufficientBalanceError` | `insufficient_balance` |
+| `ReverifyRequiredError` | `reverify_required` (403: the account owner must re-verify by email at writehuman.ai; not retried) |
+| `PlanRequiredError` | `enhanced_requires_premium` (403: `enhanced=True` on a Standard plan; `upgrade_url` says where to upgrade; nothing charged; not retried) |
+| `FeatureUnavailableError` | `enhanced_unavailable` (403: the enhanced model is switched off for everyone; send without `enhanced`; nothing charged; not retried) |
 | `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
 | `ModerationError` | `moderation_blocked` |
 | `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |

{writehuman-0.1.0 → writehuman-0.2.0}/pyproject.toml

@@ -1,33 +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"]
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "writehuman"
+version = "0.2.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 → writehuman-0.2.0}/src/writehuman/__init__.py

@@ -1,47 +1,51 @@
-"""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",
-]
+"""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.2.0"
+
+from .client import DEFAULT_BASE_URL, USER_AGENT, AsyncWriteHuman, WriteHuman  # noqa: E402
+from .errors import (  # noqa: E402
+    APIError,
+    AuthenticationError,
+    BillingError,
+    ClientTimeoutError,
+    ConnectionError,
+    FeatureUnavailableError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    ModerationError,
+    NoSubscriptionError,
+    PlanRequiredError,
+    ProcessingError,
+    ProtocolError,
+    RateLimitError,
+    ReverifyRequiredError,
+    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",
+    "ReverifyRequiredError", "PlanRequiredError", "FeatureUnavailableError",
+    "InvalidRequestError", "ModerationError", "RateLimitError", "ServiceUnavailableError", "ServerTimeoutError",
+    "ProcessingError", "BillingError", "ProtocolError", "ClientTimeoutError", "ConnectionError",
+    "HumanizeResponse", "DetectResponse", "UsageResponse", "WordsRemaining", "ErrorCode",
+]

{writehuman-0.1.0 → writehuman-0.2.0}/src/writehuman/_policy.py

@@ -1,83 +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
+"""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 → writehuman-0.2.0}/src/writehuman/client.py

@@ -4,6 +4,7 @@
     wh = WriteHuman("wh_live_...")
     out = wh.humanize("Artificial intelligence has transformed ...", tone="professional")
     print(out["results"][0], out["words_remaining"]["total"])
+    out = wh.humanize("...", enhanced=True)  # Premium plans: the enhanced model
 
     from writehuman import AsyncWriteHuman
     async with AsyncWriteHuman("wh_live_...") as wh:
@@ -70,12 +71,15 @@ class _Base:
         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]:
+    def _humanize_body(text: str, tone: Optional[str], language: Optional[str], enhanced: bool) -> 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
+        if enhanced:
+            # only when asked for, so a default request's body is unchanged
+            body["enhanced"] = True
         return body
 
     @staticmethod
@@ -105,8 +109,12 @@ class WriteHuman(_Base):
         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]
+                 enhanced: bool = False, timeout: Optional[float] = None) -> HumanizeResponse:
+        """`enhanced=True` serves the request with the enhanced model (Premium plans and above;
+        the response's `model` says which model served it). On a Standard plan it raises
+        PlanRequiredError with `upgrade_url`; while the enhanced model is switched off it raises
+        FeatureUnavailableError. Nothing is charged for either."""
+        return self._call("humanize", self._humanize_body(text, tone, language, enhanced), timeout)  # type: ignore[return-value]
 
     def detect(self, text: str, *, language: Optional[str] = None, include_sentences: bool = False,
                timeout: Optional[float] = None) -> DetectResponse:
@@ -182,8 +190,12 @@ class AsyncWriteHuman(_Base):
         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]
+                       enhanced: bool = False, timeout: Optional[float] = None) -> HumanizeResponse:
+        """`enhanced=True` serves the request with the enhanced model (Premium plans and above;
+        the response's `model` says which model served it). On a Standard plan it raises
+        PlanRequiredError with `upgrade_url`; while the enhanced model is switched off it raises
+        FeatureUnavailableError. Nothing is charged for either."""
+        return await self._call("humanize", self._humanize_body(text, tone, language, enhanced), timeout)  # type: ignore[return-value]
 
     async def detect(self, text: str, *, language: Optional[str] = None, include_sentences: bool = False,
                      timeout: Optional[float] = None) -> DetectResponse:

{writehuman-0.1.0 → writehuman-0.2.0}/src/writehuman/errors.py

@@ -5,6 +5,7 @@
     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"}
+    upgrade_url      on PlanRequiredError: where the account owner upgrades the plan
 """
 from typing import Optional
 
@@ -17,13 +18,15 @@ class WriteHumanError(Exception):
     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):
+                 retry_after: Optional[float] = None, words_remaining: Optional[WordsRemaining] = None,
+                 upgrade_url: Optional[str] = None):
         super().__init__(message)
         self.message = message
         self.status = status
         self.code = code
         self.retry_after = retry_after
         self.words_remaining = words_remaining
+        self.upgrade_url = upgrade_url
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.message!r}, status={self.status}, code={self.code!r})"
@@ -49,6 +52,26 @@ class InsufficientBalanceError(WriteHumanError):
     kind = "insufficient_balance"
 
 
+class ReverifyRequiredError(WriteHumanError):
+    """reverify_required (403): the account must be re-verified by email. The account owner
+    signs in at writehuman.ai to continue. Never retried."""
+    kind = "reverify_required"
+
+
+class PlanRequiredError(WriteHumanError):
+    """enhanced_requires_premium (403): the request asked for a feature the plan does not
+    include (`enhanced=True` on a Standard plan). `upgrade_url` is where to upgrade; or send
+    the request without the feature. Nothing is charged. Never retried."""
+    kind = "plan_required"
+
+
+class FeatureUnavailableError(WriteHumanError):
+    """enhanced_unavailable (403): the feature the request asked for is switched off on the
+    API for every account right now (`enhanced=True` while the enhanced model is off). Send
+    the request without it. Upgrading does not help. Nothing is charged. Never retried."""
+    kind = "feature_unavailable"
+
+
 class InvalidRequestError(WriteHumanError):
     """invalid_request, forbidden_param, word_limit."""
     kind = "invalid_request"
@@ -104,6 +127,9 @@ KIND_BY_CODE = {
     "missing_api_key": "authentication", "invalid_api_key": "authentication",
     "no_subscription": "no_subscription",
     "insufficient_balance": "insufficient_balance",
+    "reverify_required": "reverify_required",
+    "enhanced_requires_premium": "plan_required",
+    "enhanced_unavailable": "feature_unavailable",
     "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",
@@ -114,8 +140,8 @@ KIND_BY_CODE = {
 }
 
 CLASS_BY_KIND = {cls.kind: cls for cls in (
-    APIError, AuthenticationError, NoSubscriptionError, InsufficientBalanceError, InvalidRequestError,
-    ModerationError, RateLimitError, ServiceUnavailableError, ServerTimeoutError, ProcessingError, BillingError,
+    APIError, AuthenticationError, NoSubscriptionError, InsufficientBalanceError, ReverifyRequiredError,
+    PlanRequiredError, FeatureUnavailableError, InvalidRequestError, ModerationError, RateLimitError, ServiceUnavailableError, ServerTimeoutError, ProcessingError, BillingError,
 )}
 
 
@@ -130,5 +156,7 @@ def error_from_body(status: int, body: object, retry_after: Optional[float]) ->
     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")
+    up = body.get("upgrade_url")
     return cls(body["error"], status=status, code=code, retry_after=retry_after,
-               words_remaining=wr if isinstance(wr, dict) else None)
+               words_remaining=wr if isinstance(wr, dict) else None,
+               upgrade_url=up if isinstance(up, str) else None)

{writehuman-0.1.0 → writehuman-0.2.0}/src/writehuman/types.py

@@ -1,155 +1,173 @@
-# 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"
+# GENERATED from src/openapi.json by sdk/gen_types.py. Do not edit; run the generator.
+# Contract version 1.2.
+from typing import Any, List, Literal, Optional, TypedDict
+
+API_VERSION = "v1.2"
+
+
+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]
+    # Serve this request with our enhanced model. Premium plans and above; on a Standard plan `true` returns `403 enhanced_requires_premium`. Must be a JSON boolean.
+    enhanced: bool
+
+
+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"
+    # Which model served the request: `enhanced` when the request was sent with `enhanced: true`, else `standard`.
+    model: Literal["standard", "enhanced"]
+
+
+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",
+    "reverify_required",
+    "enhanced_requires_premium",
+    "enhanced_unavailable",
+    "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"
+
+
+class _ErrorResponseWithUpgradeOptional(TypedDict, total=False):
+    # Where to upgrade the plan. Present on `enhanced_requires_premium`.
+    upgrade_url: str
+
+
+class ErrorResponseWithUpgrade(_ErrorResponseWithUpgradeOptional):
+    # Human-readable error message.
+    error: str
+    code: "ErrorCode"

{writehuman-0.1.0 → writehuman-0.2.0}/src/writehuman.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: writehuman
-Version: 0.1.0
+Version: 0.2.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
@@ -44,6 +44,16 @@ print(score["ai_probability"], score["predicted_class"])
 print(wh.usage())
 ```
 
+Premium plans and above can ask for the enhanced model. On a Standard plan this raises
+`PlanRequiredError` (nothing is charged) with `upgrade_url` set; while the enhanced model is
+switched off on the API it raises `FeatureUnavailableError`, so send without `enhanced`. Every
+humanize response's `model` (`"standard"` or `"enhanced"`) says which model served it:
+
+```python
+out = wh.humanize(text, enhanced=True)
+print(out["model"])  # "enhanced"
+```
+
 Async, same methods:
 
 ```python
@@ -57,13 +67,16 @@ async with AsyncWriteHuman("wh_live_...") as wh:
 
 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`.
+`InsufficientBalanceError`, `words_remaining`; on `PlanRequiredError`, `upgrade_url`.
 
 | exception | API `code` |
 |---|---|
 | `AuthenticationError` | `missing_api_key`, `invalid_api_key` |
 | `NoSubscriptionError` | `no_subscription` |
 | `InsufficientBalanceError` | `insufficient_balance` |
+| `ReverifyRequiredError` | `reverify_required` (403: the account owner must re-verify by email at writehuman.ai; not retried) |
+| `PlanRequiredError` | `enhanced_requires_premium` (403: `enhanced=True` on a Standard plan; `upgrade_url` says where to upgrade; nothing charged; not retried) |
+| `FeatureUnavailableError` | `enhanced_unavailable` (403: the enhanced model is switched off for everyone; send without `enhanced`; nothing charged; not retried) |
 | `InvalidRequestError` | `invalid_request`, `forbidden_param`, `word_limit` |
 | `ModerationError` | `moderation_blocked` |
 | `RateLimitError` | `rate_limited`, `auth_locked_out`, `queue_full`, `queue_timeout` |