latet-client 0.1.0__py3-none-any.whl

latet_client/__init__.py

@@ -0,0 +1,58 @@
+"""A light Python client for the applications API of a Latet server: ``scan``, ``mask`` and ``unmask`` texts with an API
+key's token, so that an application masks its log lines or its documents before they leave, and restores them later;
+``forget`` takes values out of the key's vault.
+
+    from latet_client import Latet
+
+    with Latet("https://latet.example.com", token) as latet:
+        masked = latet.mask(["Invoice paid by mario.rossi@acme.it"])
+        original = latet.unmask(masked[0].text)
+
+``latet_client.langchain`` (``pip install "latet-client[langchain]"``) has a document transformer and two runnables
+for LangChain and LangGraph."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import AsyncLatet, Kind, Latet
+from .errors import (
+    Blocked,
+    ClearTextWarning,
+    ConnectionFailed,
+    Forbidden,
+    LatetError,
+    RateLimited,
+    TooLarge,
+    Unauthorized,
+    Unavailable,
+    VaultFull,
+)
+from .results import Finding, ForgetResult, MaskResult, ScanResult, UnmaskResult
+
+try:
+    __version__ = version("latet-client")
+except PackageNotFoundError:  # run from a copy of the source that was never installed
+    __version__ = "0+unknown"
+
+__all__ = [
+    "AsyncLatet",
+    "Blocked",
+    "ClearTextWarning",
+    "ConnectionFailed",
+    "Finding",
+    "Forbidden",
+    "ForgetResult",
+    "Kind",
+    "Latet",
+    "LatetError",
+    "MaskResult",
+    "RateLimited",
+    "ScanResult",
+    "TooLarge",
+    "Unauthorized",
+    "Unavailable",
+    "UnmaskResult",
+    "VaultFull",
+    "__version__",
+]

latet_client/client.py

@@ -0,0 +1,456 @@
+"""The client of a Latet server's applications API: ``scan``, ``mask``, ``unmask`` and ``forget`` with an API key's
+token, in :class:`Latet` and, with ``await``, in :class:`AsyncLatet`.
+
+A call takes one text and answers one result, or takes a list of texts and answers a list in the same order. A long
+list goes to the server in several calls, each of at most ``max_texts`` texts and ``max_bytes`` of JSON; a text larger
+than ``max_bytes`` goes alone (the server answers 413 if it is past its own limit). The texts of one call are masked
+together, so a value that a later text of the call teaches the server is masked in the earlier ones too; a value that
+only a later call teaches is not, as with any two calls. ``forget`` takes values, each once, sent in calls bound the
+same way, and answers one result: the counts of every call, summed.
+
+The token stays in the client: it is in the ``Authorization`` header of each call and nowhere else, not in a ``repr``,
+an exception's message or a log line (the client says what it does in the ``latet_client`` logger, without a token and
+without a text). A call that does not go through raises :class:`ConnectionFailed`, not ``httpx``'s own error, which
+carries the request and so its header."""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import json
+import logging
+import re
+import time
+import warnings
+from collections.abc import Callable, Iterator, Sequence
+from types import TracebackType
+from typing import Any, Literal, TypeVar, overload
+
+import httpx
+
+from .errors import BY_STATUS, ClearTextWarning, ConnectionFailed, LatetError, RateLimited
+from .results import (
+    ForgetResult,
+    MaskResult,
+    ScanResult,
+    UnmaskResult,
+    forget_results,
+    mask_results,
+    scan_results,
+    unmask_results,
+)
+
+__all__ = ["APPS_API", "AsyncLatet", "Kind", "Latet"]
+
+log = logging.getLogger(__name__)
+
+APPS_API = "/_latet/apps/v1"
+Kind = Literal["prose", "data"]
+KINDS = ("prose", "data")
+MOST_WAIT = 30.0  # seconds waited at most before one more try, whatever the server asked
+MOST_WORDS = 500  # characters kept of the server's words
+_ADDRESS = "the server's address is a URL such as https://latet.example.com, with no user name or password in it"
+_UNSENDABLE = "the token is empty, or holds a character a header cannot carry (a space, a line break)"
+_SAFE = re.compile(r"[\x21-\x7e]+")
+_SECONDS = re.compile(r"\d+(?:\.\d+)?")
+
+T = TypeVar("T")
+Reader = Callable[[Any, int], list[T]]
+
+
+def _sleep(seconds: float) -> None:
+    time.sleep(seconds)
+
+
+async def _asleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+def _address(url: str) -> httpx.URL:
+    """The server's address, as ``httpx`` reads it, or ValueError."""
+    if not isinstance(url, str):
+        raise TypeError(_ADDRESS)
+    try:
+        found = httpx.URL(url)
+    except httpx.InvalidURL:
+        raise ValueError(_ADDRESS) from None  # never the address as given: it may hold a password
+    if found.scheme not in ("http", "https") or not found.host or found.userinfo:
+        raise ValueError(_ADDRESS)
+    return found
+
+
+def _secret(token: str) -> str:
+    """The token without the line break a file ends with, or ValueError (that never quotes it)."""
+    if not isinstance(token, str):
+        raise TypeError("the token is a str")
+    token = token.strip()
+    if not _SAFE.fullmatch(token):
+        raise ValueError(_UNSENDABLE)
+    return token
+
+
+def _listed(texts: str | Sequence[str], field: str = "texts") -> tuple[bool, list[str]]:
+    """Whether ``texts`` is one text, and the texts as a list; a TypeError naming ``field`` for anything else."""
+    wrong = f"{field} is a str, or a sequence of str"
+    if isinstance(texts, str):
+        return True, [texts]
+    try:
+        listed = list(texts)
+    except TypeError:
+        raise TypeError(wrong) from None
+    if not all(isinstance(text, str) for text in listed):
+        raise TypeError(wrong)
+    return False, listed
+
+
+def _seconds(header: str | None) -> float | None:
+    """The seconds a ``Retry-After`` asks for; ``None`` for anything else than a number of them (a date is not read)."""
+    found = (header or "").strip()
+    return float(found) if _SECONDS.fullmatch(found) else None
+
+
+def _written(texts: list[str], what: str = "text") -> list[bytes]:
+    """Every text (``what``: or value) as a JSON string in UTF-8, before any call is made: a text UTF-8 cannot write (a
+    lone surrogate, as a log read with ``errors="surrogateescape"`` holds) is a ValueError naming its place and nothing
+    of it, and nothing has been sent."""
+    parts: list[bytes] = []
+    unwritable = None
+    for index, text in enumerate(texts):
+        try:
+            parts.append(json.dumps(text, ensure_ascii=False).encode("utf-8"))
+        except UnicodeEncodeError:
+            unwritable = index
+            break
+    if unwritable is not None:  # outside the handler: the error, which holds the whole text, is not its context
+        raise ValueError(f"{what} {unwritable} cannot be written as UTF-8 (a lone surrogate?): nothing was sent")
+    return parts
+
+
+def _bodies(
+    parts: list[bytes], kind: Kind | None, max_texts: int, max_bytes: int, field: str = "texts"
+) -> Iterator[tuple[bytes, int]]:
+    """The bodies of the calls that carry the texts (as ``_written`` made them; a forget's values, ``field``) in order,
+    each with how many it holds: at most ``max_texts`` of them and ``max_bytes`` bytes of compact JSON in UTF-8, as it
+    is sent. A text that is past ``max_bytes`` alone makes a call of its own."""
+    head = b'{"' + field.encode() + b'":['
+    tail = b"]}" if kind is None else b'],"kind":' + json.dumps(kind).encode() + b"}"
+    frame = len(head) + len(tail)
+    batch: list[bytes] = []
+    size = frame
+    for part in parts:
+        if batch and (len(batch) >= max_texts or size + 1 + len(part) > max_bytes):
+            yield head + b",".join(batch) + tail, len(batch)
+            batch, size = [], frame
+        size += len(part) + (1 if batch else 0)
+        batch.append(part)
+    if batch:
+        yield head + b",".join(batch) + tail, len(batch)
+
+
+def _on_this_computer(host: str) -> bool:
+    """Whether ``host`` is this computer: ``localhost`` or a loopback address (``127.0.0.0/8``, ``::1``)."""
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+class _Wire:
+    """What the two clients share: the address, the token, the limits, and how an answer is judged."""
+
+    def __init__(self, url: str, token: str, *, timeout: float, retries: int, max_texts: int, max_bytes: int) -> None:
+        if timeout <= 0 or retries < 0 or max_texts < 1 or max_bytes < 1:
+            raise ValueError("timeout is above zero, retries is zero or more, max_texts and max_bytes are one or more")
+        found = _address(url)
+        prefix = found.path.rstrip("/")
+        self._url = str(found.copy_with(path=prefix, query=None, fragment=None))
+        self._urls = {
+            operation: str(found.copy_with(path=f"{prefix}{APPS_API}/{operation}", query=None, fragment=None))
+            for operation in ("scan", "mask", "unmask", "forget")
+        }
+        self._token = _secret(token)
+        self._host = found.host
+        if found.scheme == "http" and not _on_this_computer(found.host):
+            message = f"the token and the texts travel in clear to {found.host} over http://: use an https:// address"
+            warnings.warn(message, ClearTextWarning, stacklevel=3)  # at the line that made the client
+        self._timeout = timeout
+        self._retries = retries
+        self._max_texts = max_texts
+        self._max_bytes = max_bytes
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(url={self._url!r})"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "authorization": f"Bearer {self._token}",
+            "content-type": "application/json",
+            "accept": "application/json",
+        }
+
+    def _plan(self, texts: str | Sequence[str], kind: Kind | None) -> tuple[bool, Iterator[tuple[bytes, int]]]:
+        """Whether ``texts`` is one text, and the bodies of the calls that carry it; the arguments are checked, and
+        every text written, here, before any call."""
+        if kind is not None and kind not in KINDS:
+            raise ValueError("kind is prose (text people wrote) or data (logs, records, a program's output)")
+        single, listed = _listed(texts)
+        return single, _bodies(_written(listed), kind, self._max_texts, self._max_bytes)
+
+    def _forgetting(self, values: str | Sequence[str]) -> Iterator[tuple[bytes, int]]:
+        """The bodies of the calls that carry ``values`` to forget, each once, in the order given (a value sent again
+        would be counted by a later call as not held); checked and written here, before any call."""
+        _, listed = _listed(values, "values")
+        once = list(dict.fromkeys(listed))
+        return _bodies(_written(once, "value"), None, self._max_texts, self._max_bytes, "values")
+
+    @staticmethod
+    def _summed(found: list[ForgetResult]) -> ForgetResult:
+        """The counts of every call of a forget, summed."""
+        return ForgetResult(sum(r.forgotten for r in found), sum(r.unknown for r in found))
+
+    def _unreachable(self, failure: str) -> ConnectionFailed:
+        """The error of a call that did not go through, from the name of ``httpx``'s error alone."""
+        return ConnectionFailed(0, f"the call to {self._host} did not go through ({failure})")
+
+    def _after(self, response: httpx.Response, attempt: int) -> float | None:
+        """``None`` for an answer to read; the seconds to wait before trying again, for a 429 or a 503 with tries left
+        (the ``Retry-After`` the server gave, at most ``MOST_WAIT``, else 1, 2, 4... seconds); otherwise the refusal,
+        raised."""
+        status = response.status_code
+        if status == 200:
+            return None
+        asked = _seconds(response.headers.get("retry-after"))
+        if status in (429, 503) and attempt < self._retries:
+            wait = min(asked if asked is not None else 2.0**attempt, MOST_WAIT)
+            log.debug(
+                "the server answered %s: trying again in %.1f s (%s of %s)", status, wait, attempt + 1, self._retries
+            )
+            return wait
+        words = self._words(response)
+        if status == 429:
+            raise RateLimited(status, words, asked)
+        raise BY_STATUS.get(status, LatetError)(status, words)
+
+    def _words(self, response: httpx.Response) -> str:
+        """The server's words for a refusal (``error``), printable and short, and never the token, whatever put it
+        there (a proxy that quotes the request); ``HTTP <status>`` when it gave none."""
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        said = body.get("error") if isinstance(body, dict) else None
+        words = said if isinstance(said, str) and said.strip() else f"HTTP {response.status_code}"
+        if words == f"HTTP {response.status_code}" and 300 <= response.status_code < 400:
+            words += (
+                ": the server redirected the call, which the client does not follow (use the server's final address)"
+            )
+        words = words.replace(self._token, "[token]")
+        return "".join(char for char in words if char.isprintable())[:MOST_WORDS]
+
+    @staticmethod
+    def _read(response: httpx.Response, count: int, read: Reader[T]) -> list[T]:
+        """The ``count`` results an answer holds, or a ``LatetError`` when it is not the API's."""
+        try:
+            return read(response.json(), count)
+        except ValueError:  # not JSON, or Malformed
+            words = "the answer is not the applications API's: is this the address of a Latet server?"
+            raise LatetError(response.status_code, words) from None
+
+
+class Latet(_Wire):
+    """A Latet server's applications API, for one API key's token.
+
+    ``url`` is the server's address, ``token`` an API key's token (``latet_key_...``) with the permission of each
+    operation used. ``timeout`` bounds each step of a call (connecting, sending, waiting for the answer), in seconds:
+    90 by default, longer than a server waits on its database (60 s a statement, 75 s an answer), so that a call it
+    could not answer in time comes back as a 503 rather than a :class:`ConnectionFailed`; a 429 or a 503 is tried again
+    ``retries`` times after the ``Retry-After`` the server gave (30 s at most each time) before it is raised, and a call
+    that does not go through is a :class:`ConnectionFailed`, not tried again. ``client`` is an ``httpx.Client`` of your
+    own (a proxy, a certificate, a transport); the client closes only the one it made. A plain ``http://`` address of
+    another computer is a :class:`ClearTextWarning`. It is safe to share between threads."""
+
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        *,
+        timeout: float = 90.0,
+        retries: int = 3,
+        max_texts: int = 1000,
+        max_bytes: int = 8 * 1024 * 1024,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(url, token, timeout=timeout, retries=retries, max_texts=max_texts, max_bytes=max_bytes)
+        self._owned = client is None
+        self._http = httpx.Client() if client is None else client
+
+    def __enter__(self) -> Latet:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, trace: TracebackType | None
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Closes the connections of the client it made; one it was given stays open."""
+        if self._owned:
+            self._http.close()
+
+    @overload
+    def scan(self, texts: str, *, kind: Kind = ...) -> ScanResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    def scan(self, texts: Sequence[str], *, kind: Kind = ...) -> list[ScanResult]: ...
+    def scan(self, texts: str | Sequence[str], *, kind: Kind = "prose") -> ScanResult | list[ScanResult]:
+        """Where the server's rules find values in each text; nothing is kept. ``kind`` is ``prose`` (text people
+        wrote) or ``data`` (logs, records, a program's output)."""
+        return self._run("scan", texts, kind, scan_results)
+
+    @overload
+    def mask(self, texts: str, *, kind: Kind = ...) -> MaskResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    def mask(self, texts: Sequence[str], *, kind: Kind = ...) -> list[MaskResult]: ...
+    def mask(self, texts: str | Sequence[str], *, kind: Kind = "prose") -> MaskResult | list[MaskResult]:
+        """Each text with the fakes of the API key's vault in place of its values: the same value gets the same fake
+        in every call. A text the server stopped has no ``text`` and says ``blocked``."""
+        return self._run("mask", texts, kind, mask_results)
+
+    @overload
+    def unmask(self, texts: str) -> UnmaskResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    def unmask(self, texts: Sequence[str]) -> list[UnmaskResult]: ...
+    def unmask(self, texts: str | Sequence[str]) -> UnmaskResult | list[UnmaskResult]:
+        """Each text with every fake of the API key's vault in it replaced by its value, whichever call made the
+        fake. The server writes each unmask in its administration log, and refuses one it cannot write (503)."""
+        return self._run("unmask", texts, None, unmask_results)
+
+    def forget(self, values: str | Sequence[str]) -> ForgetResult:
+        """Take values out of the API key's vault (a token with the ``forget`` permission, which no other brings): each
+        value found exactly as written, gone with its fake, which restores nothing from then on, and given a new fake
+        if it is met again. One result for all of them: how many the vault held, and how many it did not, each value
+        counted once. The server writes each call in its administration log with its counts, never a value, and
+        forgets nothing it cannot write there (503). A forget is safe to repeat: a value gone is counted as not held."""
+        found: list[ForgetResult] = []
+        for body, _ in self._forgetting(values):
+            found += self._read(self._post("forget", body), 1, forget_results)
+        return self._summed(found)
+
+    def _run(self, operation: str, texts: str | Sequence[str], kind: Kind | None, read: Reader[T]) -> T | list[T]:
+        single, planned = self._plan(texts, kind)
+        results: list[T] = []
+        for body, count in planned:
+            results += self._read(self._post(operation, body), count, read)
+        return results[0] if single else results
+
+    def _post(self, operation: str, body: bytes) -> httpx.Response:
+        attempt = 0
+        while True:
+            response, failure = None, ""
+            try:
+                response = self._http.post(
+                    self._urls[operation], content=body, headers=self._headers(), timeout=self._timeout
+                )
+            except httpx.HTTPError as exc:
+                failure = type(exc).__name__  # its name alone: it holds the request, and the request the token
+            if response is None:  # outside the handler, so the error is neither the cause nor the context
+                raise self._unreachable(failure)
+            wait = self._after(response, attempt)
+            if wait is None:
+                return response
+            _sleep(wait)
+            attempt += 1
+
+
+class AsyncLatet(_Wire):
+    """:class:`Latet` with ``await``: the same arguments, results, batches, errors and retries, over an
+    ``httpx.AsyncClient``. The batches of one call are sent one after the other."""
+
+    def __init__(
+        self,
+        url: str,
+        token: str,
+        *,
+        timeout: float = 90.0,
+        retries: int = 3,
+        max_texts: int = 1000,
+        max_bytes: int = 8 * 1024 * 1024,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(url, token, timeout=timeout, retries=retries, max_texts=max_texts, max_bytes=max_bytes)
+        self._owned = client is None
+        self._http = httpx.AsyncClient() if client is None else client
+
+    async def __aenter__(self) -> AsyncLatet:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, trace: TracebackType | None
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Closes the connections of the client it made; one it was given stays open."""
+        if self._owned:
+            await self._http.aclose()
+
+    async def close(self) -> None:
+        """The same as ``aclose``."""
+        await self.aclose()
+
+    @overload
+    async def scan(self, texts: str, *, kind: Kind = ...) -> ScanResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    async def scan(self, texts: Sequence[str], *, kind: Kind = ...) -> list[ScanResult]: ...
+    async def scan(self, texts: str | Sequence[str], *, kind: Kind = "prose") -> ScanResult | list[ScanResult]:
+        """As :meth:`Latet.scan`."""
+        return await self._run("scan", texts, kind, scan_results)
+
+    @overload
+    async def mask(self, texts: str, *, kind: Kind = ...) -> MaskResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    async def mask(self, texts: Sequence[str], *, kind: Kind = ...) -> list[MaskResult]: ...
+    async def mask(self, texts: str | Sequence[str], *, kind: Kind = "prose") -> MaskResult | list[MaskResult]:
+        """As :meth:`Latet.mask`."""
+        return await self._run("mask", texts, kind, mask_results)
+
+    @overload
+    async def unmask(self, texts: str) -> UnmaskResult: ...  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    async def unmask(self, texts: Sequence[str]) -> list[UnmaskResult]: ...
+    async def unmask(self, texts: str | Sequence[str]) -> UnmaskResult | list[UnmaskResult]:
+        """As :meth:`Latet.unmask`."""
+        return await self._run("unmask", texts, None, unmask_results)
+
+    async def forget(self, values: str | Sequence[str]) -> ForgetResult:
+        """As :meth:`Latet.forget`."""
+        found: list[ForgetResult] = []
+        for body, _ in self._forgetting(values):
+            found += self._read(await self._post("forget", body), 1, forget_results)
+        return self._summed(found)
+
+    async def _run(self, operation: str, texts: str | Sequence[str], kind: Kind | None, read: Reader[T]) -> T | list[T]:
+        single, planned = self._plan(texts, kind)
+        results: list[T] = []
+        for body, count in planned:
+            results += self._read(await self._post(operation, body), count, read)
+        return results[0] if single else results
+
+    async def _post(self, operation: str, body: bytes) -> httpx.Response:
+        attempt = 0
+        while True:
+            response, failure = None, ""
+            try:
+                response = await self._http.post(
+                    self._urls[operation], content=body, headers=self._headers(), timeout=self._timeout
+                )
+            except httpx.HTTPError as exc:
+                failure = type(exc).__name__  # its name alone: it holds the request, and the request the token
+            if response is None:  # outside the handler, so the error is neither the cause nor the context
+                raise self._unreachable(failure)
+            wait = self._after(response, attempt)
+            if wait is None:
+                return response
+            await _asleep(wait)
+            attempt += 1

latet_client/errors.py

@@ -0,0 +1,105 @@
+"""What goes wrong in a call, as errors. The server's refusal is a :class:`LatetError` of the HTTP status it answered
+and the words it gave; the statuses a program acts on are classes of their own; a call that does not reach the server is
+a :class:`ConnectionFailed`. The token of a call is in none of them: not in the message, not in the arguments, not in a
+``repr``, and not in anything an error holds (a failed connection is not chained, because ``httpx``'s own error carries
+the request and its ``Authorization`` header)."""
+
+from __future__ import annotations
+
+__all__ = [
+    "Blocked",
+    "ClearTextWarning",
+    "ConnectionFailed",
+    "Forbidden",
+    "LatetError",
+    "RateLimited",
+    "TooLarge",
+    "Unauthorized",
+    "Unavailable",
+    "VaultFull",
+]
+
+
+class LatetError(Exception):
+    """The server refused a call, or answered something the applications API does not answer. ``status`` is the HTTP
+    status (200 for an answer that was not the API's) and ``message`` the server's words for it, or ``HTTP <status>``
+    when it gave none. A 400, 404, 405, 422 or 500 is this class itself; the statuses below are its subclasses."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(status, message)
+        self.status = status
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"{self.status}: {self.message}"
+
+
+class ConnectionFailed(LatetError):
+    """The call did not go through: the server could not be reached, the connection broke or the call timed out. The
+    status is 0 and the message names the kind of failure (``ConnectError``, ``ReadTimeout``...) and the server's host.
+    It is not tried again by the client, and it is raised without ``__cause__`` or ``__context__``: ``httpx``'s own
+    error holds the request, and the request holds the token."""
+
+
+class Unauthorized(LatetError):
+    """401: no token, or one the server does not know (revoked, rotated, mistyped)."""
+
+
+class Forbidden(LatetError):
+    """403: the token lacks the permission of the operation (scan, mask or unmask), or it is a person's token, which
+    the applications API does not take."""
+
+
+class TooLarge(LatetError):
+    """413: the call is larger than the server takes (its ``apps_request_mb``, 8 MiB unless its settings say otherwise,
+    never more than its ``max_request_mb``). Send fewer bytes in a call: the client's ``max_bytes``."""
+
+
+class RateLimited(LatetError):
+    """429: too many calls, or too many refused tokens, from this address. ``retry_after`` is the seconds the server
+    asked to wait, ``None`` when it did not say. The client has waited and tried again ``retries`` times before it
+    raises this."""
+
+    def __init__(self, status: int, message: str, retry_after: float | None = None) -> None:
+        super().__init__(status, message)
+        self.retry_after = retry_after
+
+
+class Unavailable(LatetError):
+    """503: a store of the server does not answer, or its administration log did not take an unmask (nothing was
+    restored). The client has waited and tried again ``retries`` times before it raises this."""
+
+
+class VaultFull(LatetError):
+    """507: the API key's vault holds the most values it may, so the call masked nothing and nothing left in clear. An
+    administrator raises the limit (``latet server keys limit``)."""
+
+
+class Blocked(Exception):
+    """A text the server did not answer: its local reviewer stopped it, or its guard against dumps withheld it.
+    ``index`` is the place of the text in what was sent, ``reason`` the server's words (they name no value)."""
+
+    def __init__(self, index: int, reason: str) -> None:
+        super().__init__(index, reason)
+        self.index = index
+        self.reason = reason
+
+    def __str__(self) -> str:
+        return f"text {self.index} was blocked: {self.reason}"
+
+
+class ClearTextWarning(UserWarning):
+    """The client was made for a plain ``http://`` address of another computer: the token and the texts travel in
+    clear. Use an ``https://`` address. An address of this computer (``localhost``, ``127.0.0.1``, ``::1``) is not
+    warned of."""
+
+
+# The class of each status that has one.
+BY_STATUS: dict[int, type[LatetError]] = {
+    401: Unauthorized,
+    403: Forbidden,
+    413: TooLarge,
+    429: RateLimited,
+    503: Unavailable,
+    507: VaultFull,
+}

latet_client/langchain.py

@@ -0,0 +1,128 @@
+"""The LangChain extra (``pip install "latet-client[langchain]"``): :class:`LatetMasker`, a document transformer that
+masks documents before they are indexed, and :func:`mask_runnable` and :func:`unmask_runnable`, runnables that mask a
+question and restore an answer, for a chain or a node of a LangGraph graph.
+
+    masked = LatetMasker(latet).transform_documents(documents)  # before indexing them
+    # the model sees fakes, the person reads values
+    chain = mask_runnable(latet) | model | StrOutputParser() | unmask_runnable(latet)
+
+A chat model answers a message (``AIMessage``): ``StrOutputParser`` (``langchain_core.output_parsers``) gives its text,
+and ``unmask_runnable`` takes the message too, and gives its text back restored.
+
+Only a document's text is masked: its metadata is kept as it is, and holds ``latet_counts``, how many values of each
+type were masked in the text."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+try:
+    from langchain_core.documents import BaseDocumentTransformer, Document
+    from langchain_core.messages import BaseMessage
+    from langchain_core.runnables import Runnable, RunnableLambda
+except ImportError as exc:  # pragma: no cover - the message is the point
+    raise ImportError('latet_client.langchain needs LangChain\'s core: pip install "latet-client[langchain]"') from exc
+
+from .client import AsyncLatet, Kind, Latet
+from .errors import Blocked
+from .results import MaskResult
+
+__all__ = ["Blocked", "LatetMasker", "mask_runnable", "unmask_runnable"]
+
+COUNTS = "latet_counts"  # the metadata a masked document gets
+
+
+def _masked(results: Sequence[MaskResult]) -> list[str]:
+    """The masked texts; ``Blocked`` for the first the server stopped."""
+    texts = []
+    for index, result in enumerate(results):
+        if result.text is None:
+            raise Blocked(index, result.blocked or "the server did not answer this text")
+        texts.append(result.text)
+    return texts
+
+
+class LatetMasker(BaseDocumentTransformer):
+    """Documents masked by a Latet server, for a pipeline that indexes them: the same value gets the same fake in every
+    document, today and in a year, and the question that asks about it (``mask_runnable``) the same one.
+
+    ``transform_documents`` returns copies with the masked text and ``metadata["latet_counts"]``, and leaves the
+    documents it was given as they are. A document the server stopped raises :class:`Blocked` with its index and
+    nothing is returned, so no document of that batch is indexed unmasked.
+
+    ``client`` is a :class:`Latet` for ``transform_documents`` and ``atransform_documents`` (which then runs it in a
+    thread), or an :class:`AsyncLatet` for ``atransform_documents`` alone. ``kind`` is ``prose`` for text people wrote,
+    ``data`` for logs or records."""
+
+    def __init__(self, client: Latet | AsyncLatet, *, kind: Kind = "prose") -> None:
+        self.client = client
+        self.kind: Kind = kind
+
+    def transform_documents(self, documents: Sequence[Document], **kwargs: Any) -> Sequence[Document]:
+        if not isinstance(self.client, Latet):
+            raise TypeError("this masker has an AsyncLatet: use atransform_documents")
+        results = self.client.mask([document.page_content for document in documents], kind=self.kind)
+        return self._copies(documents, results)
+
+    async def atransform_documents(self, documents: Sequence[Document], **kwargs: Any) -> Sequence[Document]:
+        if not isinstance(self.client, AsyncLatet):
+            return await super().atransform_documents(documents, **kwargs)  # the sync client, in a thread
+        results = await self.client.mask([document.page_content for document in documents], kind=self.kind)
+        return self._copies(documents, results)
+
+    @staticmethod
+    def _copies(documents: Sequence[Document], results: Sequence[MaskResult]) -> list[Document]:
+        texts = _masked(results)
+        return [
+            document.model_copy(
+                update={
+                    "page_content": text,
+                    "metadata": {**document.metadata, COUNTS: dict(result.counts)},
+                }
+            )
+            for document, text, result in zip(documents, texts, results, strict=True)
+        ]
+
+
+def mask_runnable(client: Latet | AsyncLatet, *, kind: Kind = "prose") -> Runnable[str, str]:
+    """A runnable from a text to the same text masked, for the question of a RAG chain. A text the server stopped
+    raises :class:`Blocked`. With an :class:`AsyncLatet` it can only be awaited (``ainvoke``)."""
+    if isinstance(client, AsyncLatet):
+
+        async def amask(text: str) -> str:
+            return _masked([await client.mask(text, kind=kind)])[0]
+
+        return RunnableLambda(amask, name="latet_mask")
+
+    def mask(text: str) -> str:
+        return _masked([client.mask(text, kind=kind)])[0]
+
+    return RunnableLambda(mask, name="latet_mask")
+
+
+def _text(answer: str | BaseMessage) -> str:
+    """The text of a model's answer: a text as it is, a chat model's message (``AIMessage``) by its content, which must
+    be a text (a message of several parts, an image's, raises TypeError)."""
+    if isinstance(answer, BaseMessage):
+        if not isinstance(answer.content, str):
+            raise TypeError("unmask_runnable takes a message whose content is a text: put StrOutputParser() before it")
+        return answer.content
+    return answer
+
+
+def unmask_runnable(client: Latet | AsyncLatet) -> Runnable[str | BaseMessage, str]:
+    """A runnable from a text to the same text with every fake of the API key's vault replaced by its value, for the
+    answer of a model that was shown fakes: a text, or a chat model's message, whose text it gives back restored. With
+    an :class:`AsyncLatet` it can only be awaited (``ainvoke``)."""
+    if isinstance(client, AsyncLatet):
+
+        async def aunmask(answer: str | BaseMessage) -> str:
+            return (await client.unmask(_text(answer))).text
+
+        return RunnableLambda(aunmask, name="latet_unmask")
+
+    def unmask(answer: str | BaseMessage) -> str:
+        return client.unmask(_text(answer)).text
+
+    return RunnableLambda(unmask, name="latet_unmask")

latet_client/results.py

@@ -0,0 +1,153 @@
+"""What a call answers, one result for each text sent. ``scan`` says where the values are, ``mask`` the text with fakes
+in their place (and where they are in it), ``unmask`` the text with the real values back; ``forget`` how many values it
+took out of the vault, and how many the vault did not hold. Positions are Unicode code points, which is what a Python
+string indexes by."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["Finding", "ForgetResult", "MaskResult", "ScanResult", "UnmaskResult"]
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A value found in a text, or a fake put in its place: its ``type`` (``EMAIL``, ``IBAN``...), its
+    ``entity_class`` (``pii``, ``secret``... the JSON's ``class``) and where it is, ``text[start:end]``."""
+
+    type: str
+    entity_class: str
+    start: int
+    end: int
+
+
+@dataclass(frozen=True, slots=True)
+class ScanResult:
+    """Where the server's rules find values in a text: nothing is kept, no fake is made. ``counts`` is how many of each
+    type."""
+
+    findings: list[Finding]
+    counts: dict[str, int]
+
+
+@dataclass(frozen=True, slots=True)
+class MaskResult:
+    """A text masked: ``text`` has the fakes of the API key's vault in place of its values, ``replacements`` says where
+    (in ``text``), ``counts`` how many of each type. When the local reviewer or the server's guard stopped the text,
+    ``text`` is ``None`` and ``blocked`` says why. ``degraded`` names what ran weaker on the call (a detector that did
+    not read a text, a review that did not end), the same on every result of one call; empty when nothing did."""
+
+    text: str | None
+    replacements: list[Finding] = field(default_factory=list)
+    counts: dict[str, int] = field(default_factory=dict)
+    blocked: str | None = None
+    degraded: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class UnmaskResult:
+    """A text with every fake of the API key's vault in it replaced by its value; ``restored`` is how many."""
+
+    text: str
+    restored: int
+
+
+@dataclass(frozen=True, slots=True)
+class ForgetResult:
+    """Values taken out of the API key's vault: ``forgotten`` is how many it held (gone, with their fakes), ``unknown``
+    how many it did not hold, each value counted once."""
+
+    forgotten: int
+    unknown: int
+
+
+class Malformed(ValueError):
+    """An answer that is not the applications API's (a proxy's page, another service). The client never shows it: it
+    raises a ``LatetError`` in words of its own."""
+
+
+def _object(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise Malformed
+    return value
+
+
+def _text(value: Any) -> str:
+    if not isinstance(value, str):
+        raise Malformed
+    return value
+
+
+def _number(value: Any) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise Malformed
+    return value
+
+
+def _counts(value: Any) -> dict[str, int]:
+    return {_text(name): _number(count) for name, count in _object(value).items()}
+
+
+def _places(value: Any) -> list[Finding]:
+    if not isinstance(value, list):
+        raise Malformed
+    places = []
+    for item in value:
+        found = _object(item)
+        place = (
+            _text(found.get("type")),
+            _text(found.get("class")),
+            _number(found.get("start")),
+            _number(found.get("end")),
+        )
+        places.append(Finding(*place))
+    return places
+
+
+def _items(body: Any, count: int) -> list[dict[str, Any]]:
+    items = _object(body).get("results")
+    if not isinstance(items, list) or len(items) != count:
+        raise Malformed
+    return [_object(item) for item in items]
+
+
+def scan_results(body: Any, count: int) -> list[ScanResult]:
+    """The ``count`` results of a ``scan`` answer; ``Malformed`` when it is not one."""
+    return [ScanResult(_places(item.get("findings")), _counts(item.get("counts"))) for item in _items(body, count)]
+
+
+def mask_results(body: Any, count: int) -> list[MaskResult]:
+    """The ``count`` results of a ``mask`` answer, each with the call's ``degraded``; ``Malformed`` if it is not one."""
+    items = _items(body, count)
+    degraded = _object(body).get("degraded", [])
+    if not isinstance(degraded, list):
+        raise Malformed
+    weaker = tuple(_text(name) for name in degraded)
+    results = []
+    for item in items:
+        if "blocked" in item:
+            results.append(MaskResult(None, blocked=_text(item["blocked"]), degraded=weaker))
+        else:
+            text, places, counts = (
+                _text(item.get("text")),
+                _places(item.get("replacements")),
+                _counts(item.get("counts")),
+            )
+            results.append(MaskResult(text, places, counts, degraded=weaker))
+    return results
+
+
+def unmask_results(body: Any, count: int) -> list[UnmaskResult]:
+    """The ``count`` results of an ``unmask`` answer; ``Malformed`` when it is not one."""
+    return [UnmaskResult(_text(item.get("text")), _number(item.get("restored"))) for item in _items(body, count)]
+
+
+def forget_results(body: Any, count: int) -> list[ForgetResult]:
+    """The one result of a ``forget`` answer, whatever how many values it carried (``count``); ``Malformed`` when it
+    is not one."""
+    found = _object(body)
+    forgotten, unknown = _number(found.get("forgotten")), _number(found.get("unknown"))
+    if forgotten < 0 or unknown < 0:
+        raise Malformed
+    return [ForgetResult(forgotten, unknown)]

latet_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: latet-client
+Version: 0.1.0
+Summary: A light Python client for the applications API of a Latet server: scan, mask and unmask texts with an API key's token, with a LangChain extra.
+Project-URL: Homepage, https://latet.ai
+Project-URL: Documentation, https://docs.latet.ai
+Project-URL: Repository, https://github.com/Latet-AI/latet
+Project-URL: Issues, https://github.com/Latet-AI/latet/issues
+Author-email: Emanuele Casabona <siphion@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langchain,latet,llm,logs,pii,privacy,pseudonymization,rag,redaction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# latet-client
+
+A light Python client for the applications API of a [Latet](https://latet.ai) server. An application masks its log
+lines or its documents with an API key's token before they leave, and a person or a program with the right token
+restores them later. The package only talks HTTP (`httpx`): it has no detector and no model, and the server does the
+work.
+
+It is released on its own, under the MIT license, so that any application can embed it. Latet itself is under its own
+license: see [latet.ai](https://latet.ai).
+
+## Install
+
+```bash
+pip install latet-client
+pip install "latet-client[langchain]"   # with the LangChain transformer and runnables
+```
+
+Python 3.10 or newer. You need a Latet server, an API key on it, and a token of that key with the permissions of the
+operations you call: `scan`, `mask`, `unmask` or `forget` (a token with `mask` can `scan` too; `forget` is given on its
+own, and the key's first token does not have it).
+
+## Use
+
+```python
+from latet_client import Latet
+
+with Latet("https://latet.example.com", token) as latet:
+    masked = latet.mask("Invoice 12 was paid by mario.rossi@acme.it")
+    print(masked.text)  # Invoice 12 was paid by a fake address
+    print(masked.counts)  # {'EMAIL': 1}
+
+    lines = latet.mask(log_lines, kind="data")  # a list in, a list out, in the same order
+    original = latet.unmask(lines[500].text)  # needs a token with the unmask permission
+    print(original.text, original.restored)
+```
+
+One text in, one result out; a list in, a list out. `kind` is `"prose"` (text people wrote, the default) or `"data"`
+(logs, records, a program's output).
+
+- `scan(texts)` says where the server's rules find values, and keeps nothing: `ScanResult(findings, counts)`, each
+  finding `Finding(type, entity_class, start, end)` with positions in the text you sent.
+- `mask(texts)` gives each text with the fakes of the API key's vault in place of its values:
+  `MaskResult(text, replacements, counts, blocked, degraded)`, the positions of the replacements in the text it
+  answers. The same value gets the same fake in every call, on every instance of the server, for as long as the vault
+  keeps it. When the server's local reviewer stops a text, `text` is `None` and `blocked` says why. `degraded` names
+  what ran weaker on the call, if anything did.
+- `unmask(texts)` gives each text with every fake of the API key's vault replaced by its value, whichever call made it:
+  `UnmaskResult(text, restored)`. The server writes each unmask in its administration log.
+- `forget(values)` takes values out of the API key's vault: `ForgetResult(forgotten, unknown)`, how many the vault
+  held and how many it did not (see below).
+
+`AsyncLatet` is the same with `await` (`async with AsyncLatet(url, token) as latet`, `await latet.mask(...)`), over
+`httpx.AsyncClient`.
+
+### Forgetting values
+
+When a person asks that their data leave your logs' vault, a token with the `forget` permission takes their values out
+of it:
+
+```python
+with Latet("https://latet.example.com", eraser_token) as latet:
+    found = latet.forget(["mario.rossi@acme.it", "+39 347 123 4567"])
+    print(found.forgotten, found.unknown)  # how many the vault held, how many it did not
+```
+
+Each value is found exactly as you write it: another case, other spaces or another written form (`%40` for `@`) is
+another value, which the vault keeps as an entry of its own if it met it. A value forgotten goes with its fake: the
+fake restores nothing from then on, and the value gets a new fake if a text holds it again. An address at a company's
+domain keeps the domain as a value of its own (its fake is the domain of the address's fake): forget it too if it should
+go. A list goes in calls of `max_texts` values at most, each value once, and the counts are summed. The server writes
+each call in its administration log with its counts, never a value, and forgets nothing it cannot write there. A forget
+is safe to repeat: a value already gone is counted as not held. When a call of a long list fails, its error is raised
+and the counts of the calls before it are not returned: what they forgot stays forgotten, and sending the whole list
+again forgets the rest. A key's first forget after the server's upgrade first indexes what the key's local reviewer
+remembered and its history kept before it: on a key with much history it can take minutes, longer than the client's
+`timeout` (90 seconds). Give the client a longer `timeout` for it, or send the list again after a `ConnectionFailed`:
+what the server forgot meanwhile stays forgotten.
+
+The answer says whether the vault held each value, so a token with `forget` learns which values the vault knows, as one
+with `scan` or `mask` can: give it only to what needs it.
+
+### Long lists
+
+A list goes to the server in calls of at most `max_texts` texts (1000) and `max_bytes` bytes of JSON (8 MiB); a text
+larger than `max_bytes` goes alone, and the server answers 413 if it is past its own limit. Every text is checked and
+written before the first call: a text that cannot be written as UTF-8 (a lone surrogate, as a log read with
+`errors="surrogateescape"` can hold) is a `ValueError` naming its place, and nothing is sent.
+
+The calls of one list are sent one after the other, in order. The texts of one call are masked together: a value that a
+text of the call teaches the server is masked in the other texts of the call too. A value that only a later call
+teaches is not applied to the texts of the calls before it, which are already masked and answered: if that matters,
+keep the texts that must be masked together in one call (raise `max_texts` and `max_bytes`, up to what the server
+takes).
+
+### Errors and retries
+
+The server's refusal is a `LatetError(status, message)`, with the server's words as `message`:
+
+| Status | Class | Meaning |
+| --- | --- | --- |
+| 401 | `Unauthorized` | no token, or a token the server does not know |
+| 403 | `Forbidden` | the token lacks the permission, or it is a person's token |
+| 413 | `TooLarge` | the call is larger than the server takes |
+| 429 | `RateLimited` | too many calls or refused tokens; `retry_after` is the seconds the server asked |
+| 503 | `Unavailable` | a store of the server does not answer, or its log did not take an unmask or a forget |
+| 507 | `VaultFull` | the key's vault holds the most values it may; nothing was masked |
+| 0 | `ConnectionFailed` | the call did not go through: no connection, a broken one, a timeout |
+
+Only a 429 and a 503 are tried again: `retries` times (3), after the `Retry-After` the server gave (seconds; 30 at most
+each time; without it 1, 2, 4 seconds), and they are raised after that. Any other status is raised at once, and so is
+`ConnectionFailed`: a 422 means the texts name more of the vault's values than one call may weigh (send fewer texts in a
+call), and the call masked nothing; a 400, 404, 405 or 500 is a plain `LatetError`. A masking call is safe to repeat (the
+same value gets the same fake), and so are an unmask and a forget, so a program may try again after a `ConnectionFailed`
+if it wants to.
+
+`ConnectionFailed` has status 0 and a message that names the kind of failure and the server's host
+(`the call to latet.example.com did not go through (ConnectTimeout)`). It replaces `httpx`'s own error, which carries the
+request and so its `Authorization` header, and it is raised without it as `__cause__` or `__context__`.
+
+### The token
+
+The token is in the `Authorization` header of each call and nowhere else: not in an exception's message, not in a
+`repr`, not in a log line, and not in anything an error the client raises holds. Use an `https://` address for any
+server that is not on your own computer: a plain `http://` address of another computer makes the client give a
+`ClearTextWarning` (a Python warning), because the token and the texts then travel in clear. Pass your own `httpx.Client`
+(a proxy, a certificate) as `client=`; the client closes only the one it made.
+
+## LangChain and LangGraph
+
+`latet_client.langchain` masks the documents of a RAG pipeline before they are indexed, masks the question, and
+restores the model's answer:
+
+```python
+from langchain_core.runnables import RunnableLambda
+from latet_client import Latet
+from latet_client.langchain import LatetMasker, mask_runnable, unmask_runnable
+
+latet = Latet("https://latet.example.com", token)
+
+masked = LatetMasker(latet).transform_documents(documents)  # index these, not the originals
+# each has metadata["latet_counts"]: how many values of each type were masked; a blocked document raises Blocked
+
+chain = mask_runnable(latet) | RunnableLambda(ask_the_model) | unmask_runnable(latet)
+answer = chain.invoke("What did mario.rossi@acme.it pay?")  # the model sees fakes, you read the real values
+```
+
+The masked documents and the masked question share their fakes, because they come from the same API key's vault, so the
+model can tell that they speak of the same person. `unmask_runnable` takes a chat model's message (`AIMessage`) too,
+and gives its text back restored. `mask_runnable` and `unmask_runnable` are plain runnables: use them as nodes of a
+LangGraph graph as well. With an `AsyncLatet` the transformer has `atransform_documents` and the runnables
+`ainvoke`. Only a document's text is masked, not its metadata.
+
+## License
+
+MIT, see `LICENSE`.

latet_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+latet_client/__init__.py,sha256=MZknrM6DG05aI334fyO0z3FpRyMLBSTP87bAByESZMg,1589
+latet_client/client.py,sha256=Ya57xE-olVBdBofUiexdMNu3zpNtfwq6ahWgUN8iI7U,21733
+latet_client/errors.py,sha256=c8jBZUE4LBA8TN1gCDsxpjLLYlrErJvyRk5XWpSykpY,4335
+latet_client/langchain.py,sha256=OGCuorZ57osj-cELtnp5LwJ5EtK81Vm_cAvAEH9EH8g,6205
+latet_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+latet_client/results.py,sha256=QlpXjgXimj78zQ_MIMDombulLqJ9rAG8HiKhgqiikoE,5493
+latet_client-0.1.0.dist-info/METADATA,sha256=P-w_keH_5xoEdzJwJjan6IIjrnSSD1ut7q7LxIF0sjo,10583
+latet_client-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+latet_client-0.1.0.dist-info/licenses/LICENSE,sha256=OEkim3VRFk2OOsURDoHxw5_droM_kSTz6i5P_xg9IV4,1093
+latet_client-0.1.0.dist-info/RECORD,,

latet_client-0.1.0.dist-info/WHEEL

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

latet_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuele Casabona (https://latet.ai)
+
+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.