forgefile 0.1.0__py3-none-any.whl

forgefile/__init__.py

@@ -0,0 +1,52 @@
+"""Python client for the ForgeFile REST API.
+
+from forgefile import ForgeFile
+
+with ForgeFile("your-token") as api:
+    job = api.jobs.translate("contract.pdf", target_language="es")
+    api.files.wait(job.uuid)
+    api.files.download(job.uuid, "contract.es.pdf")
+"""
+
+from .client import ForgeFile
+from .config import ClientConfig
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ForbiddenError,
+    ForgeFileError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .models import Country, CreditsAndPlan, Currency, FileJob, JobStatus, Language
+from .resources import JobTimeoutError
+from .transport import HTTPTransport, HttpxTransport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ClientConfig",
+    "Country",
+    "CreditsAndPlan",
+    "Currency",
+    "FileJob",
+    "ForbiddenError",
+    "ForgeFile",
+    "ForgeFileError",
+    "HTTPTransport",
+    "HttpxTransport",
+    "JobStatus",
+    "JobTimeoutError",
+    "Language",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "TransportError",
+    "ValidationError",
+    "__version__",
+]

forgefile/client.py

@@ -0,0 +1,88 @@
+"""Entry point of the client."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from types import TracebackType
+from typing import Self
+
+import httpx
+
+from .config import DEFAULT_TIMEOUT, ClientConfig
+from .resources import Account, Files, Jobs, Public, System
+from .transport import HTTPTransport, HttpxTransport
+
+
+class ForgeFile:
+    """Client for the ForgeFile REST API.
+
+    The token is read from ``FORGEFILE_API_KEY`` when not passed explicitly;
+    public endpoints work without one.
+
+        >>> with ForgeFile() as api:
+        ...     languages = api.public.languages()
+
+    Pass ``transport=`` to replace the HTTP layer entirely — the resources
+    depend on the :class:`~forgefile.transport.HTTPTransport` protocol, not on
+    httpx. Pass ``http_client=`` to keep httpx but supply your own configured
+    client; the two are mutually exclusive.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+        transport: HTTPTransport | None = None,
+    ) -> None:
+        if transport is not None and http_client is not None:
+            raise ValueError(
+                "Pass either transport= or http_client=, not both: a custom transport "
+                "already decides how requests are sent."
+            )
+        self.config = ClientConfig.from_env(api_key, base_url, timeout)
+        self._transport: HTTPTransport = transport or HttpxTransport(self.config, http_client)
+
+    @cached_property
+    def system(self) -> System:
+        """Liveness probes."""
+        return System(self._transport)
+
+    @cached_property
+    def public(self) -> Public:
+        """Reference data that needs no token."""
+        return Public(self._transport)
+
+    @cached_property
+    def account(self) -> Account:
+        """Credits, plan and notifications."""
+        return Account(self._transport)
+
+    @cached_property
+    def files(self) -> Files:
+        """The file lifecycle."""
+        return Files(self._transport)
+
+    @cached_property
+    def jobs(self) -> Jobs:
+        """Processing endpoints."""
+        return Jobs(self._transport)
+
+    def close(self) -> None:
+        """Release the underlying connections."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        """Enter a context that closes the client on exit."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Close the client."""
+        self.close()

forgefile/config.py

@@ -0,0 +1,47 @@
+"""Client configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://forgefile.com/api/v1"
+DEFAULT_TIMEOUT = 60.0
+
+ENV_API_KEY = "FORGEFILE_API_KEY"
+ENV_BASE_URL = "FORGEFILE_BASE_URL"
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """Everything the transport needs to reach the API.
+
+    Immutable on purpose: a configured client cannot drift half-way through
+    a session.
+    """
+
+    api_key: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+
+    @classmethod
+    def from_env(
+        cls,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> ClientConfig:
+        """Build a config, falling back to environment variables."""
+        return cls(
+            api_key=api_key or os.environ.get(ENV_API_KEY),
+            base_url=(base_url or os.environ.get(ENV_BASE_URL, DEFAULT_BASE_URL)).rstrip("/"),
+            timeout=timeout,
+        )
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Headers sent with every request."""
+        headers = {"Accept": "application/json", "User-Agent": "forgefile-python/0.1.0"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers

forgefile/envelope.py

@@ -0,0 +1,32 @@
+"""The API's response envelope.
+
+Most endpoints answer ``{"success": ..., "message": ..., "data": {...}}``, but
+the liveness probes answer with a bare object. One function knows the
+difference so nothing else has to.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+_ENVELOPE_KEYS = frozenset({"success", "data"})
+
+
+def unwrap(body: Any) -> Any:
+    """Return ``data`` when ``body`` is an envelope, otherwise ``body``."""
+    if isinstance(body, Mapping) and body.keys() >= _ENVELOPE_KEYS:
+        return body["data"]
+    return body
+
+
+def collection(payload: Any, key: str) -> list[Any]:
+    """Return a list from ``payload``, which may nest it under ``key``.
+
+    ``/public/languages`` returns ``{"languages": [...]}`` while other
+    endpoints return the list directly.
+    """
+    if isinstance(payload, Mapping):
+        nested = payload.get(key)
+        return list(nested) if isinstance(nested, list) else []
+    return list(payload) if isinstance(payload, list) else []

forgefile/errors.py

@@ -0,0 +1,146 @@
+"""Exceptions raised by the client.
+
+Every failed response is turned into an exception by :func:`build_error`, which
+is the single place that knows how to read the API's error envelope. Subclasses
+customise their own construction through :meth:`APIError.from_envelope`, so
+adding a status-specific error needs no change to the transport.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Self
+
+
+class ForgeFileError(Exception):
+    """Base class for every error raised by this client."""
+
+
+class TransportError(ForgeFileError):
+    """The request never produced an HTTP response (network, DNS, timeout)."""
+
+
+class APIError(ForgeFileError):
+    """The API answered with a non-success status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        error_code: str | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.context: Mapping[str, Any] = context or {}
+
+    @classmethod
+    def from_envelope(
+        cls,
+        message: str,
+        *,
+        status_code: int,
+        error_code: str | None,
+        context: Mapping[str, Any],
+        headers: Mapping[str, str],
+    ) -> Self:
+        """Build the exception. Subclasses may read extra headers."""
+        del headers
+        return cls(message, status_code=status_code, error_code=error_code, context=context)
+
+    def __str__(self) -> str:
+        """Render as ``[status error_code] message``."""
+        return f"[{self.status_code} {self.error_code or 'http_error'}] {self.message}"
+
+
+class AuthenticationError(APIError):
+    """No token was sent, or the token is not valid (HTTP 401)."""
+
+
+class ForbiddenError(APIError):
+    """The token is valid but not allowed to perform this action (HTTP 403)."""
+
+
+class NotFoundError(APIError):
+    """The addressed resource does not exist (HTTP 404)."""
+
+
+class ValidationError(APIError):
+    """The payload was rejected (HTTP 422). Field errors live in ``context``."""
+
+
+class ServerError(APIError):
+    """ForgeFile failed to handle the request (HTTP 5xx)."""
+
+
+class RateLimitError(APIError):
+    """The rate limit was exhausted (HTTP 429)."""
+
+    def __init__(self, *args: Any, retry_after: int | None = None, **kwargs: Any) -> None:
+        """Record how long the caller was asked to wait, when the API said so."""
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+    @classmethod
+    def from_envelope(
+        cls,
+        message: str,
+        *,
+        status_code: int,
+        error_code: str | None,
+        context: Mapping[str, Any],
+        headers: Mapping[str, str],
+    ) -> Self:
+        """Build the error, reading ``Retry-After`` from the response headers."""
+        return cls(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            context=context,
+            retry_after=_positive_int(headers.get("retry-after")),
+        )
+
+
+_BY_STATUS: dict[int, type[APIError]] = {
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def build_error(
+    *,
+    status_code: int,
+    body: Any,
+    headers: Mapping[str, str],
+) -> APIError:
+    """Turn a failed response into the most specific exception available."""
+    message = f"HTTP {status_code}"
+    error_code: str | None = None
+    context: Mapping[str, Any] = {}
+
+    if isinstance(body, Mapping):
+        message = str(body.get("message") or message)
+        raw_code = body.get("error_code")
+        error_code = str(raw_code) if raw_code is not None else None
+        raw_context = body.get("context")
+        if isinstance(raw_context, Mapping):
+            context = raw_context
+
+    cls = ServerError if status_code >= 500 else _BY_STATUS.get(status_code, APIError)
+    return cls.from_envelope(
+        message,
+        status_code=status_code,
+        error_code=error_code,
+        context=context,
+        headers=headers,
+    )
+
+
+def _positive_int(value: str | None) -> int | None:
+    return int(value) if value and value.isdigit() else None

forgefile/models.py

@@ -0,0 +1,97 @@
+"""Response models.
+
+Only fields observed on the live API are typed explicitly. Every model accepts
+extra keys, which stay reachable through ``model_extra`` — a server-side
+addition reaches the caller instead of raising.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+
+class JobStatus(StrEnum):
+    """States this client recognises.
+
+    The API may report others, so branch on :attr:`FileJob.is_finished` rather
+    than on membership of this enum.
+    """
+
+    PENDING = "pending"
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    @property
+    def is_terminal(self) -> bool:
+        """True for states that will not change again."""
+        return self in {JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED}
+
+
+class FileJob(_Model):
+    """A file submitted for processing."""
+
+    uuid: str
+    status: str | None = None
+    original_name: str | None = None
+    created_at: str | None = None
+
+    @property
+    def state(self) -> JobStatus | None:
+        """``status`` as an enum member, or ``None`` if absent or unrecognised."""
+        if self.status is None:
+            return None
+        try:
+            return JobStatus(self.status)
+        except ValueError:
+            return None
+
+    @property
+    def is_finished(self) -> bool:
+        """True once the job reached a state that will not change again."""
+        state = self.state
+        return state is not None and state.is_terminal
+
+    @property
+    def succeeded(self) -> bool:
+        """True when the job finished and produced a result."""
+        return self.state is JobStatus.COMPLETED
+
+
+class Language(_Model):
+    """A language offered for translation."""
+
+    code: str
+    name: str
+    native: str | None = None
+
+
+class Country(_Model):
+    """A country the API recognises."""
+
+    code: str | None = None
+    name: str | None = None
+    native: str | None = None
+
+
+class Currency(_Model):
+    """A currency available for billing."""
+
+    code: str | None = None
+    name: str | None = None
+
+
+class CreditsAndPlan(_Model):
+    """Remaining credits and the plan they belong to."""
+
+    credits: int | None = None
+    plan: dict[str, Any] | None = None

forgefile/resources/__init__.py

@@ -0,0 +1,9 @@
+"""Resource groups exposed on :class:`forgefile.ForgeFile`."""
+
+from .account import Account
+from .files import Files, JobTimeoutError
+from .jobs import Jobs
+from .public import Public
+from .system import System
+
+__all__ = ["Account", "Files", "JobTimeoutError", "Jobs", "Public", "System"]

forgefile/resources/_base.py

@@ -0,0 +1,52 @@
+"""Shared plumbing for resource groups.
+
+Reading a model, reading a collection and posting a multipart upload are the
+three shapes every resource needs. They live here once.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from ..envelope import collection
+from ..transport import HTTPTransport
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+class Resource:
+    """Base for every resource group, holding the transport seam."""
+
+    def __init__(self, transport: HTTPTransport) -> None:
+        self._transport = transport
+
+    def _fetch(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        """Raw payload of a GET."""
+        return self._transport.request("GET", path, params=params)
+
+    def _fetch_one(self, model: type[ModelT], path: str) -> ModelT:
+        """GET a single object and validate it."""
+        return model.model_validate(self._fetch(path))
+
+    def _fetch_many(self, model: type[ModelT], path: str, *, key: str) -> list[ModelT]:
+        """GET a collection — nested under ``key`` or returned bare — and validate it."""
+        return [model.model_validate(item) for item in collection(self._fetch(path), key)]
+
+    def _upload(
+        self,
+        model: type[ModelT],
+        path: str,
+        source: str | Path,
+        data: Mapping[str, Any] | None = None,
+    ) -> ModelT:
+        """POST a file as multipart and validate the returned object."""
+        file = Path(source)
+        with file.open("rb") as handle:
+            payload = self._transport.request(
+                "POST", path, data=data, files={"file": (file.name, handle)}
+            )
+        return model.model_validate(payload)

forgefile/resources/account.py

@@ -0,0 +1,28 @@
+"""The authenticated user's account."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models import CreditsAndPlan
+from ._base import Resource
+
+
+class Account(Resource):
+    """Credits, plan and notifications of the token holder."""
+
+    def credits_and_plan(self) -> CreditsAndPlan:
+        """Remaining credits together with the current plan."""
+        return self._fetch_one(CreditsAndPlan, "/user/credits-and-plan")
+
+    def notifications(self) -> Any:
+        """Notifications raised for the account."""
+        return self._fetch("/notifications")
+
+    def referral_stats(self) -> Any:
+        """Referral totals for the account."""
+        return self._fetch("/referrals/stats")
+
+    def subscription_plans(self) -> Any:
+        """Plans available to this account."""
+        return self._fetch("/subscription/plans")

forgefile/resources/files.py

@@ -0,0 +1,96 @@
+"""Stored files: upload, inspect, wait, download, delete."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Any
+
+from ..errors import ForgeFileError
+from ..models import FileJob
+from ._base import Resource
+
+Sleep = Callable[[float], None]
+Clock = Callable[[], float]
+
+
+class JobTimeoutError(ForgeFileError):
+    """A job did not reach a terminal state within the allotted time."""
+
+
+class Files(Resource):
+    """The file lifecycle, independent of what is being done to the file."""
+
+    def upload(self, source: str | Path) -> FileJob:
+        """Upload a file without starting any processing.
+
+        The API caps uploads at 10 MB.
+        """
+        return self._upload(FileJob, "/files", source)
+
+    def list(self) -> list[FileJob]:
+        """Files belonging to the token holder."""
+        return self._fetch_many(FileJob, "/files", key="files")
+
+    def get(self, uuid: str) -> FileJob:
+        """Current state of one file, including its job status."""
+        return self._fetch_one(FileJob, f"/files/{uuid}")
+
+    def result(self, uuid: str) -> Any:
+        """Structured output of a finished job — text, segments, metadata."""
+        return self._fetch(f"/files/{uuid}/result")
+
+    def download(self, uuid: str, destination: str | Path) -> Path:
+        """Stream the produced file to ``destination``."""
+        return self._transport.download(f"/files/{uuid}/download", Path(destination))
+
+    def delete(self, uuid: str) -> None:
+        """Remove a file and everything derived from it."""
+        self._transport.request("DELETE", f"/files/{uuid}")
+
+    def wait(
+        self,
+        uuid: str,
+        *,
+        timeout: float = 600.0,
+        interval: float = 3.0,
+        sleep: Sleep = time.sleep,
+        clock: Clock = time.monotonic,
+    ) -> FileJob:
+        """Block until the job finishes and return its final state.
+
+        Raises :class:`JobTimeoutError` if ``timeout`` elapses first. The job
+        keeps running server-side, so calling again resumes waiting.
+        """
+        deadline = clock() + timeout
+        while True:
+            job = self.get(uuid)
+            if job.is_finished:
+                return job
+            if clock() >= deadline:
+                raise JobTimeoutError(
+                    f"File {uuid} still reports status {job.status!r} after {timeout:g}s"
+                )
+            sleep(interval)
+
+    def track(
+        self,
+        uuid: str,
+        *,
+        interval: float = 3.0,
+        sleep: Sleep = time.sleep,
+    ) -> Iterator[FileJob]:
+        """Yield every observed state until the job finishes.
+
+        Use it to report progress instead of blocking silently:
+
+            for job in api.files.track(uuid):
+                print(job.status)
+        """
+        while True:
+            job = self.get(uuid)
+            yield job
+            if job.is_finished:
+                return
+            sleep(interval)

forgefile/resources/jobs.py

@@ -0,0 +1,56 @@
+"""Processing endpoints — one call uploads the file and starts the work.
+
+Each method is a thin, self-documenting wrapper over the shared multipart
+upload; the differences between them are the endpoint and the extra fields.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import FileJob
+from ._base import Resource
+
+
+class Jobs(Resource):
+    """Translate, transcribe, convert, OCR, summarize, rewrite and compress."""
+
+    def translate(
+        self,
+        source: str | Path,
+        *,
+        target_language: str,
+        source_language: str | None = None,
+    ) -> FileJob:
+        """Translate a document, keeping its original layout.
+
+        Omit ``source_language`` to let ForgeFile detect it.
+        """
+        data = {"target_language": target_language}
+        if source_language is not None:
+            data["source_language"] = source_language
+        return self._upload(FileJob, "/files/translate", source, data)
+
+    def transcribe(self, source: str | Path) -> FileJob:
+        """Transcribe audio or video into timecoded text."""
+        return self._upload(FileJob, "/files/transcribe", source)
+
+    def convert(self, source: str | Path, *, to_format: str) -> FileJob:
+        """Convert a file to ``to_format`` (for example ``"pdf"``)."""
+        return self._upload(FileJob, "/files/convert", source, {"to_format": to_format})
+
+    def ocr(self, source: str | Path) -> FileJob:
+        """Extract text from an image."""
+        return self._upload(FileJob, "/files/ocr", source)
+
+    def summarize(self, source: str | Path) -> FileJob:
+        """Summarize a document."""
+        return self._upload(FileJob, "/files/summarize", source)
+
+    def rewrite(self, source: str | Path) -> FileJob:
+        """Rewrite the contents of a document."""
+        return self._upload(FileJob, "/files/rewrite", source)
+
+    def compress(self, source: str | Path) -> FileJob:
+        """Reduce the size of a document or media file."""
+        return self._upload(FileJob, "/files/compress", source)

forgefile/resources/public.py

@@ -0,0 +1,32 @@
+"""Reference data. No authentication required."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models import Country, Currency, Language
+from ._base import Resource
+
+
+class Public(Resource):
+    """Catalogues of languages, countries, currencies and plans."""
+
+    def languages(self) -> list[Language]:
+        """Every language available for translation."""
+        return self._fetch_many(Language, "/public/languages", key="languages")
+
+    def countries(self) -> list[Country]:
+        """Countries known to the API."""
+        return self._fetch_many(Country, "/public/countries", key="countries")
+
+    def currencies(self) -> list[Currency]:
+        """Currencies available for billing."""
+        return self._fetch_many(Currency, "/public/currencies", key="currencies")
+
+    def timezones(self) -> Any:
+        """Timezones the API accepts. Shape is passed through unmodified."""
+        return self._fetch("/public/timezones")
+
+    def translation_formats(self) -> Any:
+        """File formats accepted by the translation endpoints."""
+        return self._fetch("/public/translation/supported-formats")

forgefile/resources/system.py

@@ -0,0 +1,23 @@
+"""Service health and metadata. No token required."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import Resource
+
+
+class System(Resource):
+    """Liveness probes. These answer without the usual envelope."""
+
+    def health(self) -> Any:
+        """``{"status": "ok"}`` when the API is serving."""
+        return self._fetch("/health")
+
+    def ping(self) -> Any:
+        """``{"pong": true}``."""
+        return self._fetch("/ping")
+
+    def status(self) -> Any:
+        """Service status detail."""
+        return self._fetch("/status")

forgefile/transport.py

@@ -0,0 +1,133 @@
+"""HTTP transport.
+
+:class:`HTTPTransport` is the seam the resources depend on. Swap in your own
+implementation for tests, recording proxies or a different HTTP library —
+nothing above this module knows about httpx.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, BinaryIO, Protocol, runtime_checkable
+
+import httpx
+
+from .config import ClientConfig
+from .envelope import unwrap
+from .errors import APIError, TransportError, build_error
+
+Files = Mapping[str, tuple[str, BinaryIO]]
+
+
+@runtime_checkable
+class HTTPTransport(Protocol):
+    """Everything the resource layer needs from an HTTP client."""
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
+        files: Files | None = None,
+    ) -> Any:
+        """Perform a request and return the unwrapped payload."""
+        ...
+
+    def download(self, path: str, destination: Path) -> Path:
+        """Stream a binary response to ``destination``."""
+        ...
+
+    def close(self) -> None:
+        """Release underlying connections."""
+        ...
+
+
+class HttpxTransport:
+    """:class:`HTTPTransport` backed by :mod:`httpx`."""
+
+    def __init__(self, config: ClientConfig, client: httpx.Client | None = None) -> None:
+        """Build a transport, optionally reusing a configured httpx client."""
+        self._client = client or httpx.Client(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=config.timeout,
+            follow_redirects=True,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        data: Mapping[str, Any] | None = None,
+        files: Files | None = None,
+    ) -> Any:
+        """Send a request and return the unwrapped payload."""
+        try:
+            response = self._client.request(method, path, params=params, data=data, files=files)
+        except httpx.HTTPError as exc:
+            raise TransportError(f"Request to {path} failed: {exc}") from exc
+        return unwrap(self._payload(response))
+
+    def download(self, path: str, destination: Path) -> Path:
+        """Stream to a sibling ``.part`` file, then rename into place.
+
+        A failure mid-stream must not leave a truncated file that looks
+        complete, so ``destination`` only appears once every byte has arrived.
+        """
+        try:
+            with self._client.stream("GET", path) as response:
+                if response.is_error:
+                    response.read()
+                    raise build_error(
+                        status_code=response.status_code,
+                        body=_json_or_none(response),
+                        headers=response.headers,
+                    )
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                partial = destination.with_name(f"{destination.name}.part")
+                try:
+                    with partial.open("wb") as handle:
+                        for chunk in response.iter_bytes():
+                            handle.write(chunk)
+                    partial.replace(destination)
+                except BaseException:
+                    partial.unlink(missing_ok=True)
+                    raise
+        except httpx.HTTPError as exc:
+            raise TransportError(f"Download of {path} failed: {exc}") from exc
+        return destination
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._client.close()
+
+    @staticmethod
+    def _payload(response: httpx.Response) -> Any:
+        """Decoded body, or the mapped exception when the response is an error."""
+        if response.is_error:
+            raise build_error(
+                status_code=response.status_code,
+                body=_json_or_none(response),
+                headers=response.headers,
+            )
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise APIError("Response was not JSON", status_code=response.status_code) from exc
+
+
+def _json_or_none(response: httpx.Response) -> Any:
+    """Parsed body, or ``None`` when it is absent or not JSON."""
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return None

forgefile-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: forgefile
+Version: 0.1.0
+Summary: Python client for the ForgeFile REST API — translate, transcribe, convert, OCR, summarize and rewrite files.
+Project-URL: Homepage, https://forgefile.com
+Project-URL: Documentation, https://forgefile.com/docs
+Project-URL: Source, https://github.com/ForgeFile/forgefile-python
+Project-URL: Issues, https://github.com/ForgeFile/forgefile-python/issues
+Project-URL: Changelog, https://github.com/ForgeFile/forgefile-python/blob/main/CHANGELOG.md
+Author-email: ForgeFile <support@forgefile.com>
+License: MIT
+License-File: LICENSE
+Keywords: api-client,file-conversion,forgefile,ocr,transcription,translation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# forgefile-python
+
+Python client for the [ForgeFile](https://forgefile.com) REST API — translate, transcribe,
+convert, OCR, summarize and rewrite files.
+
+Requires Python 3.11+.
+
+## Install
+
+```bash
+pip install forgefile
+```
+
+## Quick start
+
+```python
+from forgefile import ForgeFile
+
+with ForgeFile("your-token") as api:
+    job = api.jobs.translate("contract.pdf", target_language="es")
+    api.files.wait(job.uuid)
+    api.files.download(job.uuid, "contract.es.pdf")
+```
+
+The token is read from `FORGEFILE_API_KEY` when the first argument is omitted.
+Public endpoints need no token at all:
+
+```python
+with ForgeFile() as api:
+    for language in api.public.languages():
+        print(language.code, language.name)
+```
+
+## Processing a file
+
+Every job endpoint uploads the file and starts the work in one call, returning a `FileJob`
+whose `uuid` identifies it from then on.
+
+```python
+api.jobs.translate("contract.pdf", target_language="de")  # source_language is optional
+api.jobs.transcribe("interview.mp3")
+api.jobs.convert("report.docx", to_format="pdf")
+api.jobs.ocr("receipt.jpg")
+api.jobs.summarize("paper.pdf")
+api.jobs.rewrite("draft.docx")
+api.jobs.compress("scan.pdf")
+```
+
+Uploads are capped at 10 MB by the API.
+
+### Waiting for the result
+
+`wait()` blocks until the job reaches a terminal state and raises `JobTimeoutError` if it
+does not. The job keeps running server-side, so calling again resumes waiting.
+
+```python
+finished = api.files.wait(job.uuid, timeout=900, interval=5)
+
+if finished.succeeded:
+    transcript = api.files.result(job.uuid)  # structured output
+    api.files.download(job.uuid, "interview.srt")
+```
+
+`track()` yields every observed state instead, for progress reporting:
+
+```python
+for state in api.files.track(job.uuid, interval=5):
+    print(state.status)
+```
+
+Branch on `job.is_finished` and `job.succeeded` rather than comparing status strings — a
+status this client does not recognise is never treated as finished, so a wait loop cannot
+end early on a state it has not seen.
+
+## Errors
+
+Every failure raises a subclass of `ForgeFileError` carrying the API's stable `error_code`,
+so you can branch on the code rather than on message text.
+
+```python
+from forgefile import RateLimitError, ValidationError
+
+try:
+    api.jobs.translate("contract.pdf", target_language="es")
+except ValidationError as exc:
+    print(exc.context)  # field errors
+except RateLimitError as exc:
+    print(f"retry in {exc.retry_after}s")
+```
+
+| Exception | Raised when |
+|---|---|
+| `AuthenticationError` | 401 — no token, or rejected |
+| `ForbiddenError` | 403 — token lacks the right |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422 — field errors in `context` |
+| `RateLimitError` | 429 — `retry_after` in seconds |
+| `ServerError` | 5xx — safe to retry with backoff |
+| `TransportError` | no response at all: DNS, TLS, timeout |
+| `JobTimeoutError` | `wait()` gave up; the job still runs |
+
+The API allows 60 requests per minute.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `FORGEFILE_API_KEY` | none — public endpoints only |
+| `base_url` | `FORGEFILE_BASE_URL` | `https://forgefile.com/api/v1` |
+| `timeout` | — | 60 seconds |
+
+## Examples
+
+Runnable scripts in [`examples/`](examples):
+
+| File | Shows |
+|---|---|
+| `01_public_data.py` | reference data without a token |
+| `02_translate_document.py` | submit, wait, download |
+| `03_transcribe_with_progress.py` | streaming progress with `track()` |
+| `04_convert_a_folder.py` | batching — submit all, then collect |
+| `05_handling_errors.py` | every failure mode and its remedy |
+| `06_custom_transport.py` | replacing the HTTP layer |
+
+## Architecture
+
+| Module | Responsibility |
+|---|---|
+| `config` | where to connect and with what headers |
+| `envelope` | the API's `{success, message, data}` wrapper — the only place that knows it |
+| `errors` | turning a failed response into the right exception |
+| `transport` | HTTP, as a `Protocol` plus an httpx implementation |
+| `resources/` | one class per endpoint group: `system`, `public`, `account`, `files`, `jobs` |
+
+Resources depend on the `HTTPTransport` protocol, never on httpx, so the HTTP layer can be
+replaced with a recorded fixture, a proxy or a different library — see
+`examples/06_custom_transport.py`.
+
+Response models accept unknown fields, which stay reachable through `model_extra`. Only
+fields observed against the live API are typed explicitly; authenticated endpoints could not
+be inspected without a token while this client was written, so their payloads are permissive
+rather than guessed.
+
+The package ships a `py.typed` marker, so your type checker sees these signatures.
+
+## Development
+
+```bash
+git clone https://github.com/ForgeFile/forgefile-python
+cd forgefile-python
+uv sync
+
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+Tests make no network calls: the resource layer runs against a fake transport, the httpx
+layer against `respx`. CI runs these commands on Python 3.11, 3.12 and 3.13.
+
+## Links
+
+- [ForgeFile](https://forgefile.com) — the product
+- [API reference](https://forgefile.com/docs)
+- [Source and issues](https://github.com/ForgeFile/forgefile-python)
+- [ForgeFile on GitHub](https://github.com/ForgeFile)
+- Support — <support@forgefile.com>
+
+MIT licensed. See [LICENSE](LICENSE).

forgefile-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+forgefile/__init__.py,sha256=F9Tatuipb_QCOhJFXCBnS33176STFWhwhUMswPKh7Co,1163
+forgefile/client.py,sha256=qtpy0rNdmhjqu73akhPZjlflWh93Q365z4OOICbpu0k,2686
+forgefile/config.py,sha256=w7rSmCcT8xL8KrqlPKtS45aO_rxzPQvnNGUbpRQNcv8,1348
+forgefile/envelope.py,sha256=ftOgjOYe1-jfhijj9suVvMSMpAnUHyB5945ZMLmPrJ8,1030
+forgefile/errors.py,sha256=1tRGnIiea1lCm3RvAIDm1QraYa7Qfg6CIFTKI3htoDc,4284
+forgefile/models.py,sha256=UEBFaqNl2Df93VP-R92j2z3dYIsKDhiCukDjjq-sDdA,2403
+forgefile/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forgefile/transport.py,sha256=8Pk6k-08RQnAKrGdNqIJMft6HymaiZjftu7MmU6z5HU,4499
+forgefile/resources/__init__.py,sha256=VmCMo-mEPxg4cwHf8_9jIzJ1RE90eF9U0R3dgRmP728,291
+forgefile/resources/_base.py,sha256=WSKSSIj1Do3NTMJOCNDxPCcVpyWQ1YYYaAysVT8HpTI,1773
+forgefile/resources/account.py,sha256=lsF3xcpZQv2D6FCh09MLBPkOqfzQjfL-nit2PSa3CXY,848
+forgefile/resources/files.py,sha256=_weLdYhiVTUDo387jnSqZ_jacWWuuLourNlxfHYSwew,2998
+forgefile/resources/jobs.py,sha256=XsKX6bFbIDq3bbgNJKruJG4kghs5_zsYaldXGjuo2YI,2048
+forgefile/resources/public.py,sha256=yU3wvrPBP5xTHIMAt0xJrVc1dAG2D3hXkV52rGNBJVk,1136
+forgefile/resources/system.py,sha256=UTaT_ugUPOF1xLRpM1qb2jczKaEbBYBvaRhZ48VILDI,568
+forgefile-0.1.0.dist-info/METADATA,sha256=5HhXVsdBOpZHm45pPBaLNGyFVU1F1kdK-MvQM595ofQ,6720
+forgefile-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+forgefile-0.1.0.dist-info/licenses/LICENSE,sha256=3rVNFhRxnfjSxi2stNMxxydST1W0hF0--xnAAgWn0xs,1066
+forgefile-0.1.0.dist-info/RECORD,,

forgefile-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

forgefile-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeFile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.