clocked-sdk 0.2.0__py3-none-any.whl

clocked_sdk/__init__.py

@@ -0,0 +1,46 @@
+"""Python client for the Clocked API (https://clocked.rezolve.ai).
+
+>>> from clocked_sdk import Clocked
+>>> client = Clocked()  # reads CLOCKED_API_KEY
+>>> result = client.decide(
+...     state="My laptop will not turn on, even when connected to its charger.",
+...     questions={"needs_it_help": {"type": "noul", "instructions": "Does the requester need help with an IT problem?"}},
+... )
+>>> result["answers"], result.model_ms
+"""
+
+from ._version import __version__
+from .async_client import AsyncClocked
+from .client import DEFAULT_BASE_URL, DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT, Clocked, Result
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    ClockedError,
+    ConflictError,
+    InsufficientCreditsError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "Clocked",
+    "AsyncClocked",
+    "Result",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_MAX_ATTEMPTS",
+    "ClockedError",
+    "ValidationError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "PermissionDeniedError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "APIConnectionError",
+    "RequestTimeoutError",
+]

clocked_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

clocked_sdk/async_client.py

@@ -0,0 +1,472 @@
+"""Native asynchronous Clocked client, sharing the synchronous client's contract."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional, Union
+from urllib.parse import quote
+
+import httpx
+
+from .client import (
+    DEFAULT_BASE_URL, DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT,
+    Images, JSONObject, Result, _BaseClocked, _DISCONNECTS, _TransportFailure, _retry_after, _retryable,
+)
+from .errors import ClockedError, _error_for_response
+
+__all__ = ["AsyncClocked"]
+
+
+class AsyncClocked(_BaseClocked):
+    """Asynchronous Clocked API client with the same arguments and results as Clocked.
+
+    Share one client across concurrent asyncio tasks on the same event loop.
+    Every endpoint is awaited. Use ``async with`` or ``await client.aclose()``
+    after outstanding requests finish to release the connection pool. Closing
+    a client leaves it reusable, like ``Clocked.close()``.
+
+    Constructor options, error classes, retries, and per-call idempotency
+    semantics match Clocked. Cancellation propagates without a retry; stopping
+    the local await does not cancel work already accepted by the server.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_attempts: int = DEFAULT_MAX_ATTEMPTS,
+        retry_base_delay: float = 0.5,
+        retry_max_delay: float = 8.0,
+    ) -> None:
+        super().__init__(
+            api_key, base_url=base_url, timeout=timeout, max_attempts=max_attempts,
+            retry_base_delay=retry_base_delay, retry_max_delay=retry_max_delay,
+        )
+        self._http: Optional[httpx.AsyncClient] = None
+
+    def __repr__(self) -> str:
+        return f"AsyncClocked(base_url={self.base_url!r})"
+
+    async def __aenter__(self) -> AsyncClocked:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close this client's connections. The client stays usable."""
+        client, self._http = self._http, None
+        if client is not None:
+            await client.aclose()
+
+    async def close(self) -> None:
+        """Alias for :meth:`aclose`; await it to release connections."""
+        await self.aclose()
+
+    # Endpoints ---------------------------------------------------------------
+
+    async def decide(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        state: Union[str, Mapping[str, Any], Sequence[Any], None] = None,
+        questions: Optional[Mapping[str, Mapping[str, Any]]] = None,
+        images: Optional[Images] = None,
+        instructions: Optional[str] = None,
+        calibration_temperature: Optional[float] = None,
+        rotations: Optional[int] = None,
+        documents: Optional[Sequence[Mapping[str, str]]] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Answer yes/no (``noul``), choice, multiselect and score questions.
+
+        ``POST /clocked/decide``. Pass ``state`` (text, an object or a list;
+        an empty state is answered from the question alone) or ``images``,
+        and ``questions`` keyed by name. Returns ``{model, answers, usage}``.
+        """
+        return await self._call(
+            "decide",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            state=state,
+            questions=questions,
+            images=images,
+            instructions=instructions,
+            calibration_temperature=calibration_temperature,
+            rotations=rotations,
+            documents=documents,
+        )
+
+    async def extract(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        text: Optional[str] = None,
+        images: Optional[Images] = None,
+        fields: Optional[Mapping[str, Union[str, Mapping[str, Any]]]] = None,
+        instructions: Optional[str] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Extract values verbatim from ``text`` or ``images``.
+
+        ``POST /clocked/extract``. Each of ``fields`` (1 to 64) is a
+        description string, an empty dict, or a dict with ``description``,
+        ``list`` and ``max_items``.
+        """
+        return await self._call(
+            "extract",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            text=text,
+            images=images,
+            fields=fields,
+            instructions=instructions,
+        )
+
+    async def fill(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        text: Optional[str] = None,
+        images: Optional[Images] = None,
+        fields: Optional[Mapping[str, Mapping[str, Any]]] = None,
+        instructions: Optional[str] = None,
+        reference_date: Optional[str] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Fill a complete record: extract, choice, multiselect, score, yes_no and generate fields.
+
+        ``POST /clocked/fill``. ``reference_date`` (``YYYY-MM-DD``) anchors
+        relative dates for generated date fields.
+        """
+        return await self._call(
+            "fill",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            text=text,
+            images=images,
+            fields=fields,
+            instructions=instructions,
+            reference_date=reference_date,
+        )
+
+    async def pii(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        text: Optional[str] = None,
+        images: Optional[Images] = None,
+        entities: Union[Sequence[str], Mapping[str, Any], None] = None,
+        allow: Optional[Sequence[str]] = None,
+        deny: Union[Sequence[str], Mapping[str, str], None] = None,
+        anonymize: Union[str, Mapping[str, str], None] = None,
+        threshold: Optional[float] = None,
+        mask_keep: Optional[int] = None,
+        max_items: Optional[int] = None,
+        instructions: Optional[str] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Find personal data and return a transformed copy of the text.
+
+        ``POST /clocked/pii``. ``entities`` lists catalog kinds or maps kinds
+        to custom descriptions (default: nine catalog kinds). ``anonymize`` is
+        ``replace``, ``mask``, ``hash``, ``redact`` or a per-kind mapping.
+        """
+        return await self._call(
+            "pii",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            text=text,
+            images=images,
+            entities=entities,
+            allow=allow,
+            deny=deny,
+            anonymize=anonymize,
+            threshold=threshold,
+            mask_keep=mask_keep,
+            max_items=max_items,
+            instructions=instructions,
+        )
+
+    async def injection(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        text: Optional[str] = None,
+        images: Optional[Images] = None,
+        source: Optional[str] = None,
+        categories: Optional[Sequence[str]] = None,
+        instructions: Optional[str] = None,
+        threshold: Optional[float] = None,
+        evidence: Optional[bool] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Detect prompt injection in a user message or in retrieved content.
+
+        ``POST /clocked/injection``. ``source`` is ``user`` (default) or
+        ``content``.
+        """
+        return await self._call(
+            "injection",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            text=text,
+            images=images,
+            source=source,
+            categories=categories,
+            instructions=instructions,
+            threshold=threshold,
+            evidence=evidence,
+        )
+
+    async def script(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        script: Optional[str] = None,
+        images: Optional[Images] = None,
+        categories: Optional[Sequence[str]] = None,
+        instructions: Optional[str] = None,
+        threshold: Optional[float] = None,
+        evidence: Optional[bool] = None,
+        rotations: Optional[int] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Classify whether a script's behavior is harmful, with the lines that explain it.
+
+        ``POST /clocked/script``. The script is read as data; nothing runs.
+        """
+        return await self._call(
+            "script",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            script=script,
+            images=images,
+            categories=categories,
+            instructions=instructions,
+            threshold=threshold,
+            evidence=evidence,
+            rotations=rotations,
+        )
+
+    async def grounding(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        documents: Optional[Sequence[Union[str, Mapping[str, Any]]]] = None,
+        images: Optional[Images] = None,
+        answer: Optional[str] = None,
+        question: Optional[str] = None,
+        claims: Optional[Sequence[str]] = None,
+        instructions: Optional[str] = None,
+        threshold: Optional[float] = None,
+        evidence: Optional[str] = None,
+        rotations: Optional[int] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Check each claim in ``answer`` against ``documents`` or ``images``.
+
+        ``POST /clocked/grounding``. ``evidence`` is ``all``, ``flagged``
+        (default) or ``none``.
+        """
+        return await self._call(
+            "grounding",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            documents=documents,
+            images=images,
+            answer=answer,
+            question=question,
+            claims=claims,
+            instructions=instructions,
+            threshold=threshold,
+            evidence=evidence,
+            rotations=rotations,
+        )
+
+    async def compare(
+        self,
+        request: Optional[JSONObject] = None,
+        /,
+        *,
+        documents: Optional[Sequence[Union[str, Mapping[str, Any]]]] = None,
+        threshold: Optional[float] = None,
+        evidence: Optional[str] = None,
+        rotations: Optional[int] = None,
+        kinds: Optional[bool] = None,
+        debug: Optional[bool] = None,
+        instructions: Optional[str] = None,
+        idempotency_key: Union[str, uuid.UUID, None] = None,
+        timeout: Optional[float] = None,
+        max_attempts: Optional[int] = None,
+    ) -> Result:
+        """Find duplicates, shared facts and conflicts across 2 to 20 text documents.
+
+        ``POST /clocked/compare``. ``evidence`` is ``flagged`` (default),
+        ``all`` or ``none``. Compare reads text only.
+        """
+        return await self._call(
+            "compare",
+            request,
+            idempotency_key,
+            timeout,
+            max_attempts,
+            documents=documents,
+            threshold=threshold,
+            evidence=evidence,
+            rotations=rotations,
+            kinds=kinds,
+            debug=debug,
+            instructions=instructions,
+        )
+
+    async def _call(
+        self,
+        endpoint: str,
+        request: Optional[JSONObject],
+        idempotency_key: Union[str, uuid.UUID, None],
+        timeout: Optional[float],
+        max_attempts: Optional[int],
+        /,
+        **fields: Any,
+    ) -> Result:
+        # Only local serialization/file reads use a worker. HTTP and backoff
+        # run natively on the event loop, with cancellation between attempts.
+        payload, key, wait, attempts = await asyncio.to_thread(
+            self._prepare, request, idempotency_key, timeout, max_attempts, **fields
+        )
+        return await self._send(endpoint, payload, key, wait, attempts)
+
+    async def _send(self, endpoint: str, payload: bytes, key: str, timeout: float, max_attempts: int) -> Result:
+        outcome_unknown = False
+        refreshed = False
+        attempt = 0
+        while True:
+            attempt += 1
+            retry_after: Optional[float] = None
+            try:
+                status, headers, raw = await self._post(endpoint, payload, key, timeout)
+            except _TransportFailure as transport:
+                cause = transport.cause
+                if transport.reused and not refreshed and _is_disconnect(cause):
+                    # Match Clocked's one immediate, uncounted refresh of a
+                    # reused connection. The same key safely recovers its work.
+                    refreshed = True
+                    attempt -= 1
+                    outcome_unknown = True
+                    continue
+                failure: ClockedError = self._connection_error(
+                    cause, key, attempt, timeout, timed_out=isinstance(cause, httpx.TimeoutException)
+                )
+                retry = True
+                outcome_unknown = True
+            else:
+                if 200 <= status < 300:
+                    return self._result(status, headers, raw, key, attempt)
+                failure = _error_for_response(status, headers, raw, idempotency_key=key, attempts=attempt)
+                retry = _retryable(status, failure.retry_as_new, outcome_unknown)
+                if status >= 500 and not failure.retry_as_new:
+                    outcome_unknown = True
+                retry_after = _retry_after(headers)
+            if not retry or attempt >= max_attempts:
+                raise failure
+            await asyncio.sleep(self._delay(attempt, retry_after))
+
+    def _connection(self) -> httpx.AsyncClient:
+        if self._http is None:
+            proxy = self._proxy
+            proxy_url = None
+            if proxy is not None:
+                host = f"[{proxy.host}]" if ":" in proxy.host else proxy.host
+                proxy_url = httpx.Proxy(f"http://{host}:{proxy.port}", headers=proxy.headers)
+            # SDK retry state is the only retry policy. Proxy selection and TLS
+            # context are shared with the sync client, including OS proxy rules.
+            transport = httpx.AsyncHTTPTransport(
+                verify=self._ssl if self._ssl is not None else True,
+                proxy=proxy_url,
+                retries=0,
+                trust_env=False,
+                limits=httpx.Limits(max_connections=None, max_keepalive_connections=20),
+            )
+            self._http = httpx.AsyncClient(transport=transport, follow_redirects=False, trust_env=False)
+        return self._http
+
+    async def _post(self, endpoint: str, payload: bytes, key: str, timeout: float) -> tuple[int, dict[str, str], bytes]:
+        reused = True
+
+        async def trace(event_name: str, info: dict[str, Any]) -> None:
+            nonlocal reused
+            if event_name in ("connection.connect_tcp.started", "connection.connect_unix_socket.started"):
+                reused = False
+
+        try:
+            async with self._connection().stream(
+                "POST",
+                f"{self.base_url}/{quote(endpoint)}",
+                content=payload,
+                headers=self._request_headers(key),
+                timeout=timeout,
+                extensions={"trace": trace},
+            ) as response:
+                # Like the sync transport, request identity encoding and pass
+                # the actual response bytes to our shared JSON/error decoder.
+                raw = b"".join([part async for part in response.aiter_raw()])
+                return response.status_code, dict(response.headers), raw
+        except httpx.TransportError as cause:
+            raise _TransportFailure(cause, reused) from cause
+
+
+def _is_disconnect(cause: BaseException) -> bool:
+    """HTTPX's wrappers around the sync client's refreshable disconnects."""
+    seen: set[int] = set()
+    pending = [cause]
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        if isinstance(current, _DISCONNECTS):
+            return True
+        if isinstance(current, httpx.RemoteProtocolError) and str(current) == "Server disconnected without sending a response.":
+            return True
+        pending.extend(error for error in (current.__cause__, current.__context__) if error is not None)
+    return False