multipletools 0.1.0__py3-none-any.whl

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/_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/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/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/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/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/py.typed

@@ -0,0 +1 @@
+

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+multipletools/__init__.py,sha256=2Qtt1SIa8zwdwZPc-EGrL-OfNmF8J73NtUqn6La3JQA,635
+multipletools/_http.py,sha256=vNwD-p3HHQ_FKPfnqyKgCESvXvA9UBhnlT9JrrxYvnQ,3729
+multipletools/client.py,sha256=fpTH98-7X1whBN0gdEdETY7gSL0DgnCyvtR4eI8k0-8,1332
+multipletools/exceptions.py,sha256=6Ix-xYf76K2-9Wis8iDGuFiyzqt2zSjNGtToGyaf9xM,1000
+multipletools/jobs.py,sha256=i3VRs8oum2KhkMbLYf_OEhiR2gT4UUEASV0wBqKtguI,3005
+multipletools/models.py,sha256=fA2Hwl7Vte3ShofciJ_Ji2HrkWm9KOcSZHCsLs117ZE,2778
+multipletools/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+multipletools/tools.py,sha256=QV8SMgSM5HHR3GS8Z1TAN6EKbh5eJDLstwhP3hbpBIk,684
+multipletools-0.1.0.dist-info/METADATA,sha256=qrVZTUshGjRRglmgFP3zi38wo53nL4Z_RHcwgYp6XfU,2369
+multipletools-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+multipletools-0.1.0.dist-info/top_level.txt,sha256=JJEg9m6NFvTzxwvdfbonsyix75cVymVrbwSNpG5bqgw,14
+multipletools-0.1.0.dist-info/RECORD,,

multipletools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

multipletools-0.1.0.dist-info/top_level.txt

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