matelab-python-sdk 0.1.0a7__tar.gz → 0.1.0a9__tar.gz

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/.github/workflows/release.yml

@@ -23,6 +23,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           version: "0.11.32"
+          python-version: ${{ matrix.python-version }}
       - name: Sync locked environment
         run: uv sync --frozen --python "${{ matrix.python-version }}"
       - name: Check generated wire models
@@ -53,6 +54,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           version: "0.11.32"
+          python-version: "3.14"
       - name: Verify tag and configure timestamp
         shell: bash
         run: |

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/AGENTS.md

@@ -62,6 +62,8 @@
 - mutation 默认不自动重试。multipart 或 stream 只有在确认可重放时才能重试；download stream 不自动重放，
   必须支持显式关闭。
 - HTTP/transport、Provider business/authentication、Wire Contract/schema 和 client usage 错误必须稳定区分。
+- 每个公开 `MatelabError` 必须直接提供稳定的集成级 `category` 和保守的 `retryable`；HTTP status 只用于诊断，
+  下游不得重新解释 Provider 数字 code 才能决定恢复类别。
 - password、token、SSO code/key、临时附件凭证、原始文件内容和敏感 payload 不得进入日志、异常或提交内容。
 
 ## 测试与质量门槛

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.0a9 - 2026-08-04
+
+- Breaking: removes `MatelabProviderErrorKind` and `MatelabProviderError.kind`; Provider wire codes now map directly
+  to the final `MatelabErrorCategory`, which integrations consume through `MatelabError.category`. This public API
+  removal requires a subsequent SemVer-appropriate release before distribution. Operation-specific code `0`/`10`
+  success handling and the bounded code `5` authentication refresh remain unchanged.
+- Adds a conservative `retryable` flag to every public SDK error.
+
+## 0.1.0a8 - 2026-08-04
+
+- Adds a unified `MatelabErrorCategory` and conservative `retryable` flag to every public SDK error, centralizing
+  Provider error semantics so integrations no longer reinterpret `MatelabProviderErrorKind`.
+
 ## 0.1.0a7 - 2026-08-04
 
 - Replaces the hand-maintained wire-validation rule tables with deterministic generated JSON Schema 2020-12 rules.

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a7
+Version: 0.1.0a9
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a7`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a9`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.3.0` Contract Release. The sole release pin is
@@ -58,7 +58,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a9-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -85,25 +85,30 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
-| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
-| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
-
-`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
-rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
-`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
-behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
+`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
+Provider details:
+
+| Error | Category | Retryable | Meaning and normal response |
+|---|---|---:|---|
+| `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
+| `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
+| `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
+
+For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
+unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
+are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
+operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
+`MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
-success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
+success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
-error.
+never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
+interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
+mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
+that evidence.
 
 ### Session ownership
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a7`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a9`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.3.0` Contract Release. The sole release pin is
@@ -31,7 +31,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a9-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -58,25 +58,30 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
-| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
-| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
-
-`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
-rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
-`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
-behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
+`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
+Provider details:
+
+| Error | Category | Retryable | Meaning and normal response |
+|---|---|---:|---|
+| `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
+| `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
+| `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
+
+For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
+unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
+are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
+operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
+`MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
-success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
+success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
-error.
+never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
+interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
+mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
+that evidence.
 
 ### Session ownership
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a7"
+version = "0.1.0a9"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/scripts/check_installed_package.py

@@ -17,6 +17,9 @@ def main() -> None:
             raise RuntimeError(f"Public symbol {name} leaks a generated wire type.")
     if not files(matelab).joinpath("py.typed").is_file():
         raise RuntimeError("The installed wheel does not contain matelab/py.typed.")
+    error = matelab.MatelabUsageError("invalid input")
+    if error.category is not matelab.MatelabErrorCategory.VALIDATION or error.retryable:
+        raise RuntimeError("The installed package does not expose stable integration error semantics.")
 
 
 if __name__ == "__main__":

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/src/matelab/__init__.py

@@ -115,9 +115,9 @@ from matelab.domains.users import UserRef, UserSummary
 from matelab.errors import (
     MatelabAuthenticationError,
     MatelabError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -165,9 +165,9 @@ __all__ = [
     "LiteratureStoredMetadata",
     "MatelabAuthenticationError",
     "MatelabError",
+    "MatelabErrorCategory",
     "MatelabProtocolError",
     "MatelabProviderError",
-    "MatelabProviderErrorKind",
     "MatelabTransportError",
     "MatelabUsageError",
     "NotebookCollection",

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/src/matelab/_transport.py

@@ -14,9 +14,9 @@ from matelab._generated import models as wire_models
 from matelab._wire_validation import validate_request
 from matelab.errors import (
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -42,12 +42,12 @@ def _provider_error(code: int, *, provider_message: str) -> MatelabAuthenticatio
         return MatelabAuthenticationError("Matelab authentication failed.")
     if code == 5:
         return MatelabAuthenticationError("Access token expired.")
-    kind = {
-        2: MatelabProviderErrorKind.REJECTED,
-        3: MatelabProviderErrorKind.SERVER,
-        4: MatelabProviderErrorKind.VALIDATION,
-    }.get(code, MatelabProviderErrorKind.UNKNOWN)
-    return MatelabProviderError(provider_message, kind=kind)
+    category = {
+        2: MatelabErrorCategory.BUSINESS,
+        3: MatelabErrorCategory.UPSTREAM,
+        4: MatelabErrorCategory.VALIDATION,
+    }.get(code, MatelabErrorCategory.UPSTREAM)
+    return MatelabProviderError(provider_message, category=category)
 
 
 class Encoding(StrEnum):

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/src/matelab/errors.py

@@ -1,34 +1,41 @@
 from enum import StrEnum
 
 
-class MatelabError(Exception):
-    """Base class for stable Matelab SDK errors."""
+class MatelabErrorCategory(StrEnum):
+    """Stable integration-level recovery category for an SDK error."""
 
+    AUTHENTICATION = "authentication"
+    BUSINESS = "business"
+    VALIDATION = "validation"
+    UPSTREAM = "upstream"
 
-class MatelabProviderErrorKind(StrEnum):
-    """Stable interpretation of a Provider error envelope."""
 
-    REJECTED = "rejected"
-    SERVER = "server"
-    VALIDATION = "validation"
-    UNKNOWN = "unknown"
+class MatelabError(Exception):
+    """Base class for stable Matelab SDK errors."""
+
+    category: MatelabErrorCategory = MatelabErrorCategory.UPSTREAM
+    retryable: bool = False
 
 
 class MatelabProviderError(MatelabError):
     """The Provider returned a non-authentication error envelope."""
 
-    def __init__(self, message: str, *, kind: MatelabProviderErrorKind) -> None:
+    def __init__(self, message: str, *, category: MatelabErrorCategory) -> None:
         super().__init__(message)
-        self.kind = kind
+        self.category = category
 
 
 class MatelabAuthenticationError(MatelabError):
     """The Matelab session cannot authenticate Provider requests."""
 
+    category = MatelabErrorCategory.AUTHENTICATION
+
 
 class MatelabUsageError(MatelabError):
     """The requested SDK operation cannot be represented safely."""
 
+    category = MatelabErrorCategory.VALIDATION
+
 
 class MatelabTransportError(MatelabError):
     """The HTTP exchange with the Provider failed."""

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_client.py

@@ -10,9 +10,9 @@ from matelab import (
     Identity,
     MatelabAuthenticationError,
     MatelabError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     Session,
     Token,
@@ -132,7 +132,7 @@ async def test_authenticate_does_not_expose_provider_error_body() -> None:
     rendered = str(caught.value)
     assert password not in rendered
     assert rendered == "Matelab request failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 
@@ -226,7 +226,7 @@ async def test_exchange_chat_sso_code_does_not_expose_provider_error_body() -> N
     assert code not in rendered
     assert key not in rendered
     assert rendered == "Matelab request failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "payload")
 
 
@@ -365,17 +365,19 @@ def test_session_models_reject_invalid_values_and_extra_fields() -> None:
 
 
 @pytest.mark.parametrize(
-    ("code", "kind"),
+    ("code", "category"),
     [
-        (2, MatelabProviderErrorKind.REJECTED),
-        (3, MatelabProviderErrorKind.SERVER),
-        (4, MatelabProviderErrorKind.VALIDATION),
-        (11, MatelabProviderErrorKind.UNKNOWN),
-        (99, MatelabProviderErrorKind.UNKNOWN),
+        (2, MatelabErrorCategory.BUSINESS),
+        (3, MatelabErrorCategory.UPSTREAM),
+        (4, MatelabErrorCategory.VALIDATION),
+        (11, MatelabErrorCategory.UPSTREAM),
+        (99, MatelabErrorCategory.UPSTREAM),
     ],
 )
 @pytest.mark.asyncio
-async def test_provider_error_codes_are_hidden_behind_stable_kinds(code: int, kind: MatelabProviderErrorKind) -> None:
+async def test_provider_error_codes_are_hidden_behind_stable_semantics(
+    code: int, category: MatelabErrorCategory
+) -> None:
     async def handler(_: Request) -> Response:
         return Response(200, json={"code": code, "msg": "rejected", "errcode": code, "errmsg": "rejected"})
 
@@ -385,7 +387,8 @@ async def test_provider_error_codes_are_hidden_behind_stable_kinds(code: int, ki
             _ = await client.authenticate("alice@example.org", "bad-password")
 
     assert isinstance(caught.value, MatelabError)
-    assert caught.value.kind is kind
+    assert caught.value.category is category
+    assert caught.value.retryable is False
     assert not hasattr(caught.value, "code")
 
 
@@ -400,6 +403,8 @@ async def test_provider_authentication_codes_are_hidden_behind_authentication_er
         with pytest.raises(MatelabAuthenticationError) as caught:
             _ = await client.authenticate("alice@example.org", "bad-password")
 
+    assert caught.value.category is MatelabErrorCategory.AUTHENTICATION
+    assert caught.value.retryable is False
     assert not hasattr(caught.value, "code")
 
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_cloud_drive.py

@@ -12,9 +12,9 @@ from matelab import (
     CloudFile,
     CloudFileRef,
     CloudFolderRef,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     Session,
     StagedFile,
@@ -430,4 +430,4 @@ async def test_download_cloud_file_uses_identity_thumbnail_preview_and_range_str
                 CloudFileRef(cloud_file_id=501), thumbnail=True, preview=False, byte_range=ByteRange.between(1, 3)
             )
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS

matelab_python_sdk-0.1.0a9/tests/test_errors.py

@@ -0,0 +1,67 @@
+import pytest
+
+import matelab
+from matelab import (
+    MatelabAuthenticationError,
+    MatelabError,
+    MatelabErrorCategory,
+    MatelabProtocolError,
+    MatelabProviderError,
+    MatelabTransportError,
+    MatelabUsageError,
+)
+
+
+def test_provider_error_kind_is_not_part_of_public_interface() -> None:
+    assert "MatelabProviderErrorKind" not in matelab.__all__
+    assert not hasattr(matelab, "MatelabProviderErrorKind")
+
+
+def test_error_category_values_are_stable_for_integrations() -> None:
+    assert {category.name: category.value for category in MatelabErrorCategory} == {
+        "AUTHENTICATION": "authentication",
+        "BUSINESS": "business",
+        "VALIDATION": "validation",
+        "UPSTREAM": "upstream",
+    }
+
+
+@pytest.mark.parametrize(
+    ("error", "category"),
+    [
+        pytest.param(MatelabError("failure"), MatelabErrorCategory.UPSTREAM, id="base"),
+        pytest.param(MatelabAuthenticationError("failure"), MatelabErrorCategory.AUTHENTICATION, id="authentication"),
+        pytest.param(MatelabUsageError("failure"), MatelabErrorCategory.VALIDATION, id="usage"),
+        pytest.param(MatelabTransportError("failure"), MatelabErrorCategory.UPSTREAM, id="transport"),
+        pytest.param(MatelabProtocolError("failure"), MatelabErrorCategory.UPSTREAM, id="protocol"),
+    ],
+)
+def test_public_errors_expose_integration_category_and_conservative_retryability(
+    error: MatelabError, category: MatelabErrorCategory
+) -> None:
+    assert error.category is category
+    assert error.retryable is False
+
+
+@pytest.mark.parametrize(
+    "category",
+    [
+        MatelabErrorCategory.BUSINESS,
+        MatelabErrorCategory.UPSTREAM,
+        MatelabErrorCategory.VALIDATION,
+    ],
+)
+def test_provider_error_exposes_final_integration_category(category: MatelabErrorCategory) -> None:
+    error = MatelabProviderError("failure", category=category)
+
+    assert error.category is category
+    assert error.retryable is False
+    assert not hasattr(error, "kind")
+
+
+def test_transport_error_preserves_http_status_without_changing_integration_semantics() -> None:
+    error = MatelabTransportError("failure", status_code=503)
+
+    assert error.status_code == 503
+    assert error.category is MatelabErrorCategory.UPSTREAM
+    assert error.retryable is False

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_records.py

@@ -7,9 +7,9 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 from matelab import (
     AsyncMatelab,
     Identity,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     NotebookRef,
     RecordLocator,
@@ -184,7 +184,7 @@ async def test_record_domain_classifies_provider_business_errors() -> None:
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await client.records.list(notebook=notebook)
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
 
 
 @pytest.mark.asyncio

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_release.py

@@ -101,6 +101,15 @@ def test_release_version_has_one_runtime_source() -> None:
     assert all("__version__" not in path.read_text() for path in (_ROOT / "src" / "matelab").rglob("*.py"))
 
 
+def test_release_workflow_uses_python_specific_uv_cache_keys() -> None:
+    workflow = (_ROOT / ".github" / "workflows" / "release.yml").read_text()
+    test_job = workflow.partition("  test:")[2].partition("\n  build:")[0]
+    build_job = workflow.partition("  build:")[2].partition("\n  publish:")[0]
+
+    assert "          python-version: ${{ matrix.python-version }}" in test_job
+    assert '          python-version: "3.14"' in build_job
+
+
 def test_lockfile_mirrors_project_version() -> None:
     pyproject = tomllib.loads((_ROOT / "pyproject.toml").read_text())
     project = cast(dict[str, object], pyproject["project"])

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_streaming.py

@@ -6,9 +6,9 @@ from httpx2 import AsyncByteStream, AsyncClient, MockTransport, ReadError, Reque
 from matelab import (
     ByteRange,
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
     Session,
@@ -257,7 +257,7 @@ async def test_stream_classifies_json_error_without_exposing_response_body(provi
     assert _HASH not in rendered
     assert access_token not in rendered
     assert rendered == "Matelab download failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_transport.py

@@ -11,9 +11,9 @@ from matelab._generated.models import BasicSuccessResponse, RecordListResponse,
 from matelab._transport import Encoding, Operation, SessionTransport
 from matelab.errors import (
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -39,8 +39,9 @@ def _session(
     )
 
 
+@pytest.mark.parametrize("code", [0, 10])
 @pytest.mark.asyncio
-async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> None:
+async def test_transport_accepts_each_success_code_only_when_declared_for_operation(code: int) -> None:
     async def handler(request: Request) -> Response:
         assert request.method == "POST"
         assert request.url.path == "/api/eln_api/items"
@@ -48,7 +49,8 @@ async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> N
         assert request.headers["Content-Type"] == "application/json"
         assert json.loads(request.content) == {"eln": "Example Notebook"}
         return Response(
-            200, json={"code": 10, "msg": "", "errcode": 10, "errmsg": "", "items": [], "subtypes": [], "trash_num": 0}
+            200,
+            json={"code": code, "msg": "", "errcode": code, "errmsg": "", "items": [], "subtypes": [], "trash_num": 0},
         )
 
     operation = Operation(
@@ -56,7 +58,7 @@ async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> N
         path="/eln_api/items",
         encoding=Encoding.JSON,
         response_model=RecordListResponse,
-        success_codes=frozenset({0, 10}),
+        success_codes=frozenset({code}),
     )
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         transport = SessionTransport(http_client=http_client, session=_session())
@@ -104,7 +106,7 @@ async def test_transport_classifies_provider_business_errors() -> None:
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await transport.request(operation, payload={"eln": ""})
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/test_users.py

@@ -5,9 +5,9 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 
 from matelab import (
     AsyncMatelab,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
     Session,
@@ -112,7 +112,7 @@ async def test_search_users_classifies_provider_business_errors(provider_session
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await client.users.search("Example")
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
 
 
 @pytest.mark.asyncio

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/tests/typing/consumer.py

@@ -1,5 +1,8 @@
 from matelab import (
     AsyncMatelab,
+    MatelabError,
+    MatelabErrorCategory,
+    MatelabProviderError,
     NotebookCollection,
     NotebookRef,
     RecordAttachmentChange,
@@ -21,6 +24,16 @@ from matelab import (
 )
 
 
+def consume_error(error: MatelabError) -> tuple[MatelabErrorCategory, bool]:
+    category: MatelabErrorCategory = error.category
+    retryable: bool = error.retryable
+    return category, retryable
+
+
+def construct_provider_error(category: MatelabErrorCategory) -> MatelabProviderError:
+    return MatelabProviderError("failure", category=category)
+
+
 async def consume_public_types(client: AsyncMatelab) -> tuple[Session | None, NotebookCollection]:
     notebooks: NotebookCollection = await client.notebooks.list()
     session: Session | None = client.session

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a9}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a7"
+version = "0.1.0a9"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },