Release v3.1.0

Generated public mirror snapshot.

Author: Convilyn Release

CHANGELOG.md

@@ -3,6 +3,65 @@
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versioning follows [Semantic Versioning](https://semver.org/).
 
+## [3.1.0] - 2026-08-17
+
+Minor, and both halves are why: the public surface **grows** by four exception
+types, and the set of packages installed into your environment **shrinks** by
+one. Nothing is removed from the API and nothing you catch today stops being
+caught, so no migration is required.
+
+### Added
+
+- **Four typed billing refusals.** The paid path can refuse a run in four ways
+  that want four different next steps from you, and until now all four arrived
+  as a bare `APIError` — so telling "top up" from "wait" from "this workflow
+  has no price" meant string-matching `exc.code`, which is matching on
+  something we reserve the right to change.
+
+  | | status | what to do |
+  |---|---|---|
+  | `InsufficientCreditsError` | 402 | top up — carries `required_credits`, `available_credits`, `shortfall_credits` |
+  | `FreeTierBlockedError` | 403 | leave the Free plan (or fund the run) — carries `upgrade_url` |
+  | `SpecNotPricedError` | 409 | pick another workflow; retrying will not help |
+  | `ChargeUnavailableError` | 409 | transient — retry later |
+
+  **`InsufficientCreditsError` is not `QuotaExceededError`, and they share HTTP
+  402.** A quota is a ceiling you were given and it resets at the next period; a
+  balance is money you hold and it does not refill on its own. One status code,
+  two different facts about your account — so they are two types rather than one
+  type you branch on by `code`:
+
+  ```python
+  except InsufficientCreditsError as exc:
+      print(f"short by {exc.shortfall_credits} credits")   # None when unknown
+  except QuotaExceededError:
+      ...                                                  # wait, or upgrade
+  ```
+
+  `shortfall_credits` is derived from the two operands rather than sent as a
+  third field, because a third field that must agree with two others is a field
+  that can disagree with them. It is `None` — *unknown*, never zero — when the
+  refusal carried no operands, and clamped at zero if they ever disagree.
+
+  All four subclass `APIError`, so every existing `except APIError:` and
+  `except ConvilynError:` keeps catching them. **A refusal code this build does
+  not model still arrives as a plain `APIError`** with `code` and `details`
+  intact — on 402, 403 and 409 alike — so a new server signal is never an
+  unhandled crash and never a type asserting a remediation nobody verified.
+
+### Removed
+
+- **`websockets` is no longer a dependency.** It had been *required* since
+  before 3.0.0 and imported nowhere in the package since — the WebSocket
+  surface was removed in 3.0.0 (`goals.events()`, `GoalEvent`, `WebSocketError`,
+  `ws_url`) and the dependency did not follow, so every `pip install convilyn`
+  pulled a package no code could reach.
+
+  Nothing in the public API changes; there was nothing left importing it. What
+  changes is your installed environment — one fewer transitive package, one
+  fewer version-compatibility surface, one fewer CVE feed to read. That is why
+  this is a minor rather than a patch.
+
 ## [3.0.1] - 2026-08-17
 
 A fix-only release: nothing added, nothing removed from the public API. That is

docs/QUICKSTART.md

@@ -390,8 +390,33 @@ except ConvilynError as exc:      # covers every type listed below
 ```
 
 Catch a specific one when you can actually do something different about it —
-top up on `QuotaExceededError`, back off on `RateLimitError`, fall back to file
-conversion on `UnderstandUnavailableError`.
+top up on `InsufficientCreditsError`, back off on `RateLimitError`, fall back to
+file conversion on `UnderstandUnavailableError`.
+
+**`QuotaExceededError` and `InsufficientCreditsError` are both HTTP 402 and they
+are not the same thing.** A quota is a ceiling you were given and it resets at
+the next period; a balance is money you hold and it does not refill on its own.
+So they are separate types rather than one type you branch on by `code`:
+
+```python
+from convilyn import InsufficientCreditsError, QuotaExceededError
+
+try:
+    result = client.goals.run(goal_text="Summarise this", files=[file_id])
+except InsufficientCreditsError as exc:
+    # `shortfall_credits` is None when the server did not send the operands —
+    # read that as unknown, never as zero.
+    print(f"top up: short by {exc.shortfall_credits} credits")
+except QuotaExceededError:
+    print("allowance spent — wait for the next period, or upgrade")
+```
+
+The billing path refuses on three other statuses too, each wanting a different
+next step: `FreeTierBlockedError` (403 — leave the Free plan),
+`ChargeUnavailableError` (409 — transient, retry later) and `SpecNotPricedError`
+(409 — permanent for that workflow, retrying will not help). A refusal code this
+build does not model still arrives as a plain `APIError` with `code` and
+`details` intact, so a new server signal never becomes an unhandled crash.
 
 **Importable from `convilyn`:**
 
@@ -403,7 +428,11 @@ conversion on `UnderstandUnavailableError`.
 | `APIError` | the API answered with an error status |
 | `RateLimitError` | too many requests — back off and retry |
 | `QuotaExceededError` | the plan's allowance for this call is used up |
+| `InsufficientCreditsError` | your **balance** cannot fund this run — carries `required_credits` / `available_credits` / `shortfall_credits` |
 | `PlanRequiredError` | the call needs a tier this account is not on |
+| `FreeTierBlockedError` | a Free-plan gate refused the run — this workflow is not on Free, or Free's monthly cap is spent |
+| `SpecNotPricedError` | this workflow has no price configured; retrying will not help |
+| `ChargeUnavailableError` | billing could not record the charge right now — transient, retry later |
 | `RetryExhaustedError` | retried to the configured limit and still failing |
 | `S3UploadError` | the upload itself failed, before any job existed |
 | `JobFailedError` | a conversion job finished with `status=failed` |

docs/README.md

@@ -152,10 +152,12 @@ convilyn goals start "summarise these contracts" --dry-run
 ## Free to install, metered to use
 
 `pip install convilyn` is free, and everything under `convilyn local` stays free
-and unlimited — it runs on your hardware. Platform calls draw on your plan's
-quota, and the SDK raises typed `PlanRequiredError` / `QuotaExceededError`
-(both `APIError`) rather than failing opaquely. Check first with
-`client.account`.
+and unlimited — it runs on your hardware. Platform calls draw on your balance and
+your plan, and every refusal is a typed `APIError` subclass rather than an opaque
+failure: `InsufficientCreditsError` (your balance cannot fund this run — it
+carries `shortfall_credits`), `QuotaExceededError` (an allowance is spent),
+`PlanRequiredError` and `FreeTierBlockedError` (this needs a different plan).
+Check first with `client.account`.
 
 ## Known limits
 

docs/STABILITY.md

@@ -136,6 +136,16 @@ If streaming returns, it will be through a short-lived, single-use connect
 ticket — a design that shares no code with what was removed, which is the other
 reason keeping this was not "free optionality".
 
+**The dependency did not follow until 3.1.0.** `websockets` stayed a *required*
+dependency of this package for the whole of 3.0.x with zero imports anywhere in
+`src/`, so every `pip install convilyn` pulled a package no code could reach. It
+is removed in 3.1.0. Nothing about the surface changes — there was nothing left
+importing it — but the set of packages installed into your environment does,
+which is why it is a minor and not a patch. This is worth recording rather than
+quietly deleting: the removal of a *surface* and the removal of the *dependency
+that served it* are two steps, and only the first one is visible in a diff of
+the public API.
+
 ## Deprecation policy
 
 We do not remove public surface without warning. A symbol slated for

pyproject.toml

@@ -11,7 +11,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
 authors = [
-    { name = "Convilyn", email = "support@corenovus.com" },
+    { name = "Convilyn", email = "support@convilyn.com" },
 ]
 keywords = [
     "convilyn",
@@ -37,7 +37,6 @@ dependencies = [
     "httpx>=0.25.0,<1.0.0",
     "pydantic>=2.0.0,<3.0.0",
     "click>=8.0.0,<9.0.0",
-    "websockets>=13.0,<17.0",
     "typing-extensions>=4.7.0; python_version < '3.11'",
 ]
 

src/convilyn/__init__.py

@@ -38,16 +38,20 @@
 from convilyn.exceptions import (
     APIError,
     AuthError,
+    ChargeUnavailableError,
     ConvilynError,
+    FreeTierBlockedError,
     GoalJobFailedError,
     GoalJobTimeoutError,
+    InsufficientCreditsError,
     JobFailedError,
     JobTimeoutError,
     PlanRequiredError,
     QuotaExceededError,
     RateLimitError,
     RetryExhaustedError,
     S3UploadError,
+    SpecNotPricedError,
     UnderstandUnavailableError,
 )
 from convilyn.sync_client import Convilyn
@@ -105,16 +109,19 @@
     "BuilderSession",
     "BuilderTurn",
     "CatalogWorkflow",
+    "ChargeUnavailableError",
     "ConvertJob",
     "Convilyn",
     "ConvilynError",
     "CostEstimate",
     "ExponentialBackoffRetry",
     "File",
     "FileList",
+    "FreeTierBlockedError",
     "GoalJob",
     "GoalJobFailedError",
     "GoalJobTimeoutError",
+    "InsufficientCreditsError",
     "JobError",
     "JobFailedError",
     "JobTimeoutError",
@@ -132,6 +139,7 @@
     "RetryExhaustedError",
     "RetryPolicy",
     "S3UploadError",
+    "SpecNotPricedError",
     "StorageUsage",
     "StoredFile",
     "ToolCostEstimate",

src/convilyn/_internal/http.py

@@ -46,11 +46,15 @@
 from convilyn._version import __version__
 from convilyn.exceptions import (
     APIError,
+    ChargeUnavailableError,
+    FreeTierBlockedError,
+    InsufficientCreditsError,
     PlanRequiredError,
     QuotaExceededError,
     RateLimitError,
     RetryExhaustedError,
     S3UploadError,
+    SpecNotPricedError,
 )
 
 # Backend emits any of these on 402 to signal a plan-tier mismatch.
@@ -65,6 +69,26 @@
     }
 )
 
+# Backend emits either of these on 403 when a Free-plan gate refuses a run
+# before any charge (``services/billing/quote.py`` ``QuoteFreeBlocked``). Same
+# shape and same rationale as the frozenset above: a third Free gate is one
+# line here and changes no dispatch.
+_FREE_TIER_BLOCKED_CODES: frozenset[str] = frozenset(
+    {
+        "spec_not_allowed_on_free",
+        "free_cost_cap_exceeded",
+    }
+)
+
+# 409 billing refusals, keyed to their class. A dict rather than an `if`/`elif`
+# chain because the two mean OPPOSITE things about retrying — permanent vs
+# transient — and a reader should see that as two rows, not as an order of
+# tests (`coding-style.md` O).
+_BILLING_CONFLICT_ERRORS: dict[str, type[APIError]] = {
+    "SPEC_NOT_PRICED": SpecNotPricedError,
+    "CHARGE_UNAVAILABLE": ChargeUnavailableError,
+}
+
 DEFAULT_BASE_URL = "https://api.convilyn.corenovus.com"
 DEFAULT_TIMEOUT = 30.0
 ENV_BASE_URL = "CONVILYN_BASE_URL"
@@ -527,10 +551,15 @@ def _decode_error(response: httpx.Response) -> APIError:
         * 429 → :class:`RateLimitError`
         * 402 + code in :data:`_PLAN_REQUIRED_CODES` → :class:`PlanRequiredError`
         * 402 + code = ``QUOTA_EXCEEDED`` → :class:`QuotaExceededError`
+        * 402 + code = ``INSUFFICIENT_CREDITS`` → :class:`InsufficientCreditsError`
+        * 403 + code in :data:`_FREE_TIER_BLOCKED_CODES` → :class:`FreeTierBlockedError`
+        * 409 + code in :data:`_BILLING_CONFLICT_ERRORS` → that class
         * Otherwise → base :class:`APIError`
 
-    Unknown 402 codes fall through to ``APIError`` — forward-compat for
-    new tier signals the SDK doesn't know about yet.
+    Unknown codes fall through to ``APIError`` — forward-compat for signals the
+    SDK doesn't know about yet. That is deliberate on EVERY status here, not
+    just 402: a 403 the SDK cannot name is still a 403, and inventing a type for
+    it would assert a remediation nobody verified.
     """
     status = response.status_code
     try:
@@ -572,6 +601,40 @@ def _decode_error(response: httpx.Response) -> APIError:
                 ),
                 upgrade_url=upgrade_url,
             )
+        if code == "INSUFFICIENT_CREDITS":
+            # These two ride INSIDE `details`, not beside it — the refusal is
+            # built as `detail={code, message, details={requiredCredits, ...}}`
+            # (`api/v1/goal_lane/_charging.py`), so `inner` holds the dict and
+            # not the numbers. Reading them off `inner` would silently produce
+            # None on every real refusal while looking exactly like the
+            # QUOTA_EXCEEDED branch above.
+            credit_detail = details if isinstance(details, dict) else {}
+            return InsufficientCreditsError(
+                status,
+                code,
+                message,
+                details,
+                required_credits=_coerce_int(
+                    _first_present(credit_detail, "requiredCredits", "required_credits")
+                ),
+                available_credits=_coerce_int(
+                    _first_present(credit_detail, "availableCredits", "available_credits")
+                ),
+            )
+
+    if status == 403 and code in _FREE_TIER_BLOCKED_CODES:
+        return FreeTierBlockedError(
+            status,
+            code,
+            message,
+            details,
+            upgrade_url=inner.get("upgrade_url") or inner.get("upgradeUrl"),
+        )
+
+    if status == 409:
+        conflict = _BILLING_CONFLICT_ERRORS.get(code)
+        if conflict is not None:
+            return conflict(status, code, message, details)
 
     return APIError(status, code, message, details)
 
@@ -635,6 +698,25 @@ def _flatten_error_envelope(payload: dict[str, Any]) -> dict[str, Any]:
     return nested if isinstance(nested, dict) else payload
 
 
+def _first_present(payload: dict[str, Any], *keys: str) -> Any:
+    """The first key that is PRESENT, not the first that is truthy.
+
+    ``payload.get("a") or payload.get("a_snake")`` is the idiom used elsewhere
+    in this module for camel/snake aliases, and it is wrong for any field whose
+    zero value is meaningful. ``availableCredits`` is exactly that field: it is
+    ``0`` for the caller :class:`InsufficientCreditsError` exists for — someone
+    whose balance is empty — and ``0 or None`` is ``None``, so the number would
+    read as "the server did not send it" on the most common refusal there is.
+
+    Returns ``None`` when no key is present, which :func:`_coerce_int` then
+    passes through as the genuine "unknown".
+    """
+    for key in keys:
+        if key in payload:
+            return payload[key]
+    return None
+
+
 def _coerce_int(value: Any) -> int | None:
     """Best-effort ``int`` coercion for wire fields that may arrive as str."""
     if value is None:

src/convilyn/_version.py

@@ -11,4 +11,4 @@
 hardcoded constant in two places.
 """
 
-__version__ = "3.0.1"
+__version__ = "3.1.0"