multipletools 0.1.0__tar.gz

multipletools-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: multipletools
+Version: 0.1.0
+Summary: Official Python SDK for the Multiple Tools API
+Author: Abhishek Kumbhar
+Project-URL: Homepage, https://github.com/Abhiiishek44/multipletools
+Project-URL: Repository, https://github.com/Abhiiishek44/multipletools
+Project-URL: Issues, https://github.com/Abhiiishek44/multipletools/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+
+# Multiple Tools Python SDK
+
+Typed synchronous Python client for the Multiple Tools HTTP API. The SDK talks
+only to FastAPI and has no database, object-storage, Redis, Celery, or plugin
+dependencies.
+
+## Installation
+
+```bash
+pip install ./sdks/python
+```
+
+## Usage
+
+```python
+from multipletools import Client
+
+client = Client(
+    api_key="mt_live_...",
+    base_url="https://api.example.com",
+    timeout=60.0,
+)
+
+job = client.jobs.create(
+    tool="pdf_to_word",  # underscore aliases are normalized to pdf-to-word
+    file="document.pdf",
+)
+
+job = client.jobs.get(job.id)
+if job.status == "SUCCESS":
+    client.jobs.download(job.id, "converted.docx")
+
+client.close()
+```
+
+The client can also be used as a context manager. `jobs.create` generates an
+idempotency key automatically; pass `idempotency_key=` to reuse one across an
+application-level retry. Tool-specific options are sent with `options={...}`.
+If the platform cannot infer a file's MIME type, pass `media_type=` explicitly.
+
+```python
+with Client(api_key="mt_live_...", base_url="http://localhost:8000") as client:
+    tools = client.tools.list()
+    job = client.jobs.create(
+        tool="rotate-pdf",
+        file="document.pdf",
+        options={"angle": 90},
+        idempotency_key="conversion-123",
+    )
+```
+
+HTTP failures raise typed exceptions from `multipletools.exceptions`, including
+`AuthenticationError`, `PermissionDeniedError`, `ValidationError`,
+`NotFoundError`, `ConflictError`, `RateLimitError`, `TimeoutError`, and
+`ConnectionError`.

multipletools-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Multiple Tools Python SDK
+
+Typed synchronous Python client for the Multiple Tools HTTP API. The SDK talks
+only to FastAPI and has no database, object-storage, Redis, Celery, or plugin
+dependencies.
+
+## Installation
+
+```bash
+pip install ./sdks/python
+```
+
+## Usage
+
+```python
+from multipletools import Client
+
+client = Client(
+    api_key="mt_live_...",
+    base_url="https://api.example.com",
+    timeout=60.0,
+)
+
+job = client.jobs.create(
+    tool="pdf_to_word",  # underscore aliases are normalized to pdf-to-word
+    file="document.pdf",
+)
+
+job = client.jobs.get(job.id)
+if job.status == "SUCCESS":
+    client.jobs.download(job.id, "converted.docx")
+
+client.close()
+```
+
+The client can also be used as a context manager. `jobs.create` generates an
+idempotency key automatically; pass `idempotency_key=` to reuse one across an
+application-level retry. Tool-specific options are sent with `options={...}`.
+If the platform cannot infer a file's MIME type, pass `media_type=` explicitly.
+
+```python
+with Client(api_key="mt_live_...", base_url="http://localhost:8000") as client:
+    tools = client.tools.list()
+    job = client.jobs.create(
+        tool="rotate-pdf",
+        file="document.pdf",
+        options={"angle": 90},
+        idempotency_key="conversion-123",
+    )
+```
+
+HTTP failures raise typed exceptions from `multipletools.exceptions`, including
+`AuthenticationError`, `PermissionDeniedError`, `ValidationError`,
+`NotFoundError`, `ConflictError`, `RateLimitError`, `TimeoutError`, and
+`ConnectionError`.

multipletools-0.1.0/multipletools/__init__.py

@@ -0,0 +1,32 @@
+from multipletools.client import Client
+from multipletools.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    ConnectionError,
+    MultipleToolsError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+from multipletools.models import Job, Tool
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "Client",
+    "ConflictError",
+    "ConnectionError",
+    "Job",
+    "MultipleToolsError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "TimeoutError",
+    "Tool",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

multipletools-0.1.0/multipletools/_http.py

@@ -0,0 +1,121 @@
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+
+from multipletools.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+
+
+_ERROR_TYPES: dict[int, type[APIError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float | httpx.Timeout,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/") + "/",
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": "multipletools-python/0.1.0",
+            },
+        )
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        data: Mapping[str, str] | None = None,
+        files: Mapping[str, Any] | None = None,
+    ) -> Any:
+        try:
+            response = self._client.request(
+                method, path.lstrip("/"), headers=headers, data=data, files=files
+            )
+        except httpx.TimeoutException as error:
+            raise TimeoutError("The Multiple Tools API request timed out") from error
+        except httpx.RequestError as error:
+            raise ConnectionError(
+                f"Could not reach the Multiple Tools API: {error}"
+            ) from error
+        raise_for_status(response)
+        try:
+            return response.json()
+        except ValueError as error:
+            raise APIError(
+                "The Multiple Tools API returned invalid JSON",
+                status_code=response.status_code,
+                request_id=response.headers.get("x-request-id"),
+            ) from error
+
+    @contextmanager
+    def stream(self, method: str, path: str) -> Iterator[httpx.Response]:
+        try:
+            with self._client.stream(method, path.lstrip("/")) as response:
+                if not 200 <= response.status_code < 300:
+                    response.read()
+                raise_for_status(response)
+                yield response
+        except httpx.TimeoutException as error:
+            raise TimeoutError("The Multiple Tools API request timed out") from error
+        except httpx.RequestError as error:
+            raise ConnectionError(
+                f"Could not reach the Multiple Tools API: {error}"
+            ) from error
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if 200 <= response.status_code < 300:
+        return
+    details: Any = None
+    message = f"Multiple Tools API returned HTTP {response.status_code}"
+    try:
+        details = response.json()
+        if isinstance(details, dict):
+            detail = details.get("detail")
+            if isinstance(detail, str) and detail:
+                message = detail
+            elif detail is not None:
+                message = str(detail)
+    except ValueError:
+        pass
+    error_type = _ERROR_TYPES.get(response.status_code, APIError)
+    raise error_type(
+        message,
+        status_code=response.status_code,
+        request_id=response.headers.get("x-request-id"),
+        details=details,
+    )

multipletools-0.1.0/multipletools/client.py

@@ -0,0 +1,48 @@
+import re
+from types import TracebackType
+
+import httpx
+
+from multipletools._http import HttpClient
+from multipletools.jobs import Jobs
+from multipletools.tools import Tools
+
+
+_API_KEY_PATTERN = re.compile(r"^mt_live_[a-f0-9]{24}_[A-Za-z0-9_-]{32,128}$")
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "http://localhost:8000",
+        timeout: float | httpx.Timeout = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not _API_KEY_PATTERN.fullmatch(api_key):
+            raise ValueError("api_key must use the mt_live_<key_id>_<secret> format")
+        if not base_url.startswith(("http://", "https://")):
+            raise ValueError("base_url must be an absolute HTTP or HTTPS URL")
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+        )
+        self.jobs = Jobs(self._http)
+        self.tools = Tools(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()

multipletools-0.1.0/multipletools/exceptions.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+
+class MultipleToolsError(Exception):
+    """Base exception for all SDK failures."""
+
+
+class ConnectionError(MultipleToolsError):
+    """The API could not be reached."""
+
+
+class TimeoutError(MultipleToolsError):
+    """The API request exceeded its configured timeout."""
+
+
+class APIError(MultipleToolsError):
+    """The API returned a non-success response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        request_id: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = details
+
+
+class ValidationError(APIError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass

multipletools-0.1.0/multipletools/jobs.py

@@ -0,0 +1,93 @@
+import json
+import mimetypes
+import os
+from pathlib import Path
+from typing import BinaryIO, Mapping
+from urllib.parse import quote
+from uuid import uuid4
+
+from multipletools._http import HttpClient
+from multipletools.models import Job
+
+
+FileInput = str | os.PathLike[str] | BinaryIO
+
+
+class Jobs:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        tool: str,
+        file: FileInput,
+        options: Mapping[str, object] | None = None,
+        idempotency_key: str | None = None,
+        media_type: str | None = None,
+    ) -> Job:
+        canonical_tool = tool.strip().replace("_", "-")
+        if not canonical_tool:
+            raise ValueError("tool must not be empty")
+        headers = {"Idempotency-Key": idempotency_key or uuid4().hex}
+        data = {"tool": canonical_tool}
+        if options:
+            data["options"] = json.dumps(options, separators=(",", ":"))
+
+        if isinstance(file, (str, os.PathLike)):
+            path = Path(file)
+            resolved_media_type = media_type or _media_type(path.name)
+            with path.open("rb") as stream:
+                payload = self._http.request_json(
+                    "POST",
+                    "/v1/jobs",
+                    headers=headers,
+                    data=data,
+                    files={"file": (path.name, stream, resolved_media_type)},
+                )
+        else:
+            filename = Path(str(getattr(file, "name", "upload.bin"))).name
+            resolved_media_type = media_type or _media_type(filename)
+            payload = self._http.request_json(
+                "POST",
+                "/v1/jobs",
+                headers=headers,
+                data=data,
+                files={"file": (filename, file, resolved_media_type)},
+            )
+        return Job.from_dict(payload)
+
+    def get(self, job_id: str) -> Job:
+        payload = self._http.request_json("GET", f"/v1/jobs/{_job_id(job_id)}")
+        return Job.from_dict(payload)
+
+    def download(
+        self,
+        job_id: str,
+        destination: str | os.PathLike[str],
+    ) -> Path:
+        target = Path(destination)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        temporary = target.with_name(f".{target.name}.{uuid4().hex}.part")
+        try:
+            with self._http.stream(
+                "GET", f"/v1/jobs/{_job_id(job_id)}/output"
+            ) as response:
+                with temporary.open("wb") as output:
+                    for chunk in response.iter_bytes():
+                        output.write(chunk)
+            temporary.replace(target)
+        except BaseException:
+            temporary.unlink(missing_ok=True)
+            raise
+        return target
+
+
+def _job_id(job_id: str) -> str:
+    if not job_id:
+        raise ValueError("job_id must not be empty")
+    return quote(job_id, safe="")
+
+
+def _media_type(filename: str) -> str:
+    return mimetypes.guess_type(filename)[0] or "application/octet-stream"

multipletools-0.1.0/multipletools/models.py

@@ -0,0 +1,84 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal, Mapping, cast
+
+
+JobStatus = Literal["QUEUED", "RUNNING", "SUCCESS", "FAILED"]
+
+
+@dataclass(frozen=True, slots=True)
+class Job:
+    id: str
+    tool_name: str
+    tool_version: str
+    status: JobStatus
+    progress: int
+    input_filename: str
+    output_filename: str | None
+    output_url: str | None
+    error: str | None
+    created_at: datetime
+    started_at: datetime | None
+    completed_at: datetime | None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Job":
+        status = str(data["status"])
+        if status not in {"QUEUED", "RUNNING", "SUCCESS", "FAILED"}:
+            raise ValueError(f"Unknown job status: {status}")
+        progress = int(data["progress"])
+        if not 0 <= progress <= 100:
+            raise ValueError("Job progress must be between 0 and 100")
+        return cls(
+            id=str(data["id"]),
+            tool_name=str(data["tool_name"]),
+            tool_version=str(data["tool_version"]),
+            status=cast(JobStatus, status),
+            progress=progress,
+            input_filename=str(data["input_filename"]),
+            output_filename=_optional_string(data.get("output_filename")),
+            output_url=_optional_string(data.get("output_url")),
+            error=_optional_string(data.get("error")),
+            created_at=_datetime(data["created_at"]),
+            started_at=_optional_datetime(data.get("started_at")),
+            completed_at=_optional_datetime(data.get("completed_at")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    name: str
+    version: str
+    description: str
+    input_suffixes: tuple[str, ...]
+    input_media_types: tuple[str, ...]
+    output_suffix: str
+    output_media_type: str
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Tool":
+        return cls(
+            name=str(data["name"]),
+            version=str(data["version"]),
+            description=str(data["description"]),
+            input_suffixes=tuple(str(value) for value in data["input_suffixes"]),
+            input_media_types=tuple(
+                str(value) for value in data["input_media_types"]
+            ),
+            output_suffix=str(data["output_suffix"]),
+            output_media_type=str(data["output_media_type"]),
+        )
+
+
+def _datetime(value: Any) -> datetime:
+    if not isinstance(value, str):
+        raise ValueError("Expected an ISO-8601 datetime string")
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _optional_datetime(value: Any) -> datetime | None:
+    return None if value is None else _datetime(value)
+
+
+def _optional_string(value: Any) -> str | None:
+    return None if value is None else str(value)

multipletools-0.1.0/multipletools/py.typed

@@ -0,0 +1 @@
+

multipletools-0.1.0/multipletools/tools.py

@@ -0,0 +1,20 @@
+from multipletools._http import HttpClient
+from multipletools.models import Tool
+
+
+class Tools:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> list[Tool]:
+        payload = self._http.request_json("GET", "/v1/tools")
+        if not isinstance(payload, list):
+            raise ValueError("Expected the tools API to return a list")
+        return [Tool.from_dict(item) for item in payload]
+
+    def get(self, name: str) -> Tool:
+        canonical_name = name.replace("_", "-")
+        for tool in self.list():
+            if tool.name == canonical_name:
+                return tool
+        raise LookupError(f"Unknown tool: {name}")

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

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: multipletools
+Version: 0.1.0
+Summary: Official Python SDK for the Multiple Tools API
+Author: Abhishek Kumbhar
+Project-URL: Homepage, https://github.com/Abhiiishek44/multipletools
+Project-URL: Repository, https://github.com/Abhiiishek44/multipletools
+Project-URL: Issues, https://github.com/Abhiiishek44/multipletools/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+
+# Multiple Tools Python SDK
+
+Typed synchronous Python client for the Multiple Tools HTTP API. The SDK talks
+only to FastAPI and has no database, object-storage, Redis, Celery, or plugin
+dependencies.
+
+## Installation
+
+```bash
+pip install ./sdks/python
+```
+
+## Usage
+
+```python
+from multipletools import Client
+
+client = Client(
+    api_key="mt_live_...",
+    base_url="https://api.example.com",
+    timeout=60.0,
+)
+
+job = client.jobs.create(
+    tool="pdf_to_word",  # underscore aliases are normalized to pdf-to-word
+    file="document.pdf",
+)
+
+job = client.jobs.get(job.id)
+if job.status == "SUCCESS":
+    client.jobs.download(job.id, "converted.docx")
+
+client.close()
+```
+
+The client can also be used as a context manager. `jobs.create` generates an
+idempotency key automatically; pass `idempotency_key=` to reuse one across an
+application-level retry. Tool-specific options are sent with `options={...}`.
+If the platform cannot infer a file's MIME type, pass `media_type=` explicitly.
+
+```python
+with Client(api_key="mt_live_...", base_url="http://localhost:8000") as client:
+    tools = client.tools.list()
+    job = client.jobs.create(
+        tool="rotate-pdf",
+        file="document.pdf",
+        options={"angle": 90},
+        idempotency_key="conversion-123",
+    )
+```
+
+HTTP failures raise typed exceptions from `multipletools.exceptions`, including
+`AuthenticationError`, `PermissionDeniedError`, `ValidationError`,
+`NotFoundError`, `ConflictError`, `RateLimitError`, `TimeoutError`, and
+`ConnectionError`.

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

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+multipletools/__init__.py
+multipletools/_http.py
+multipletools/client.py
+multipletools/exceptions.py
+multipletools/jobs.py
+multipletools/models.py
+multipletools/py.typed
+multipletools/tools.py
+multipletools.egg-info/PKG-INFO
+multipletools.egg-info/SOURCES.txt
+multipletools.egg-info/dependency_links.txt
+multipletools.egg-info/requires.txt
+multipletools.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+httpx<1,>=0.27
+
+[test]
+pytest<9,>=8

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

@@ -0,0 +1 @@
+multipletools

multipletools-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "multipletools"
+version = "0.1.0"
+description = "Official Python SDK for the Multiple Tools API"
+readme = "README.md"
+requires-python = ">=3.10"
+
+authors = [
+    { name = "Abhishek Kumbhar" }
+]
+
+dependencies = [
+    "httpx>=0.27,<1"
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8,<9"
+]
+
+[project.urls]
+Homepage = "https://github.com/Abhiiishek44/multipletools"
+Repository = "https://github.com/Abhiiishek44/multipletools"
+Issues = "https://github.com/Abhiiishek44/multipletools/issues"
+
+[tool.setuptools.packages.find]
+include = ["multipletools*"]
+
+[tool.setuptools.package-data]
+multipletools = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

multipletools-0.1.0/setup.cfg

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

multipletools-0.1.0/tests/test_client.py

@@ -0,0 +1,166 @@
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+import httpx
+
+from multipletools import Client
+from multipletools.exceptions import AuthenticationError, ConflictError, TimeoutError
+
+
+API_KEY = "mt_live_0123456789abcdef01234567_" + "s" * 43
+
+
+def job_payload(**overrides: object) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "id": "job-123",
+        "tool_name": "pdf-to-word",
+        "tool_version": "1.0.0",
+        "status": "QUEUED",
+        "progress": 0,
+        "input_filename": "document.pdf",
+        "output_filename": None,
+        "output_url": None,
+        "error": None,
+        "created_at": "2026-09-11T10:00:00Z",
+        "started_at": None,
+        "completed_at": None,
+    }
+    payload.update(overrides)
+    return payload
+
+
+class ClientTests(unittest.TestCase):
+    def test_create_uses_generic_http_endpoint_and_normalizes_tool_alias(self) -> None:
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["request"] = request
+            captured["body"] = request.read()
+            return httpx.Response(202, json=job_payload())
+
+        transport = httpx.MockTransport(handler)
+        with tempfile.TemporaryDirectory() as directory:
+            source = Path(directory) / "document.pdf"
+            source.write_bytes(b"%PDF-test")
+            with Client(
+                api_key=API_KEY,
+                base_url="https://api.example.test",
+                transport=transport,
+            ) as client:
+                job = client.jobs.create(
+                    tool="pdf_to_word",
+                    file=source,
+                    options={"quality": "high"},
+                    idempotency_key="request-123",
+                )
+
+        request = captured["request"]
+        assert isinstance(request, httpx.Request)
+        body = captured["body"]
+        assert isinstance(body, bytes)
+        self.assertEqual(request.url.path, "/v1/jobs")
+        self.assertEqual(request.headers["authorization"], f"Bearer {API_KEY}")
+        self.assertEqual(request.headers["idempotency-key"], "request-123")
+        self.assertIn(b'pdf-to-word', body)
+        self.assertIn(b'document.pdf', body)
+        self.assertIn(json.dumps({"quality": "high"}, separators=(",", ":")).encode(), body)
+        self.assertEqual(job.id, "job-123")
+
+    def test_get_returns_typed_job(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            self.assertEqual(request.url.path, "/v1/jobs/job-123")
+            return httpx.Response(
+                200,
+                json=job_payload(
+                    status="SUCCESS",
+                    progress=100,
+                    output_filename="converted.docx",
+                    output_url="/v1/jobs/job-123/output",
+                    completed_at="2026-09-11T10:01:00+00:00",
+                ),
+            )
+
+        with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+            job = client.jobs.get("job-123")
+
+        self.assertEqual(job.status, "SUCCESS")
+        self.assertEqual(job.progress, 100)
+        self.assertEqual(job.completed_at.isoformat(), "2026-09-11T10:01:00+00:00")
+
+    def test_download_streams_to_destination(self) -> None:
+        content = b"converted-document"
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            self.assertEqual(request.url.path, "/v1/jobs/job-123/output")
+            return httpx.Response(200, content=content)
+
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "nested" / "converted.docx"
+            with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+                returned = client.jobs.download("job-123", destination)
+            self.assertEqual(returned, destination)
+            self.assertEqual(destination.read_bytes(), content)
+            self.assertEqual(list(destination.parent.glob("*.part")), [])
+
+    def test_failed_download_does_not_leave_a_partial_file(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(409, json={"detail": "Job output is not available"})
+
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "converted.docx"
+            with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+                with self.assertRaises(ConflictError):
+                    client.jobs.download("job-123", destination)
+            self.assertFalse(destination.exists())
+            self.assertEqual(list(destination.parent.glob("*.part")), [])
+
+    def test_api_errors_are_typed_and_include_details(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"detail": "Invalid API key"})
+
+        with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+            with self.assertRaises(AuthenticationError) as caught:
+                client.jobs.get("job-123")
+
+        self.assertEqual(caught.exception.status_code, 401)
+        self.assertEqual(str(caught.exception), "Invalid API key")
+
+    def test_transport_timeouts_are_wrapped(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ReadTimeout("timed out", request=request)
+
+        with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+            with self.assertRaises(TimeoutError):
+                client.jobs.get("job-123")
+
+    def test_tools_list_returns_typed_tools(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                200,
+                json=[
+                    {
+                        "name": "pdf-to-word",
+                        "version": "1.0.0",
+                        "description": "Convert PDF to Word",
+                        "input_suffixes": [".pdf"],
+                        "input_media_types": ["application/pdf"],
+                        "output_suffix": ".docx",
+                        "output_media_type": (
+                            "application/vnd.openxmlformats-officedocument."
+                            "wordprocessingml.document"
+                        ),
+                    }
+                ],
+            )
+
+        with Client(api_key=API_KEY, transport=httpx.MockTransport(handler)) as client:
+            tools = client.tools.list()
+
+        self.assertEqual(tools[0].name, "pdf-to-word")
+        self.assertEqual(tools[0].input_suffixes, (".pdf",))
+
+
+if __name__ == "__main__":
+    unittest.main()