temperkb-py 0.5.1__py3-none-any.whl

temper/__init__.py

@@ -0,0 +1,93 @@
+"""The Python client for the Temper knowledge base API.
+
+Sibling of `temper-rb` and `temper-ts`; the three are pinned to the same wire
+contracts. `temper/generated/` is emitted from the repo-root `openapi.json` — itself
+a product of the Axum router — and is NEVER hand-edited: `cargo make openapi`
+regenerates it, and `openapi-py-drift` (in `cargo make check`, and in CI) fails if the
+committed copy has fallen behind the contract.
+
+    import temper
+    from temper.generated.api.resources_api import ResourcesApi
+
+    temper.configure(base_url="https://temperkb.io")
+    client = temper.Client(temper.ClientCredentials(
+        token_url="https://temperkb.io/oauth/token",
+        client_id="tmpr_...",
+        client_secret="...",
+    ))
+
+    client.whoami()
+    client.call(lambda api: ResourcesApi(api).get_resource(uuid), idempotent=True)
+"""
+
+from temper.act import Act
+from temper.client import MAX_READ_ATTEMPTS, Client, default_backoff
+from temper.connection import (
+    SURFACE,
+    Connection,
+    api_client,
+    configure,
+    current_connection,
+    current_token,
+    reset_connection,
+    with_token,
+)
+from temper.credentials import BearerToken, ClientCredentials, Credentials
+from temper.errors import (
+    BadRequest,
+    Conflict,
+    Forbidden,
+    NotFound,
+    PermanentError,
+    RateLimited,
+    ServerError,
+    SystemAccessRequired,
+    TemperError,
+    TransientError,
+    TransportError,
+    Unauthorized,
+    map_error,
+)
+
+# The contract this package was generated against. `generate-temper-py.sh` passes
+# openapi.json's info.version to the generator as `packageVersion`, so the generated
+# tree already carries it — we alias it rather than reasserting it, and callers never
+# reach into `temper.generated` for it. Independent of `__version__`, which is the
+# SDK's own SemVer: a package version and an API version answer different questions.
+from temper.generated import __version__ as CONTRACT_VERSION
+from temper.refs import parse_ref
+from temper.version import __version__
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "MAX_READ_ATTEMPTS",
+    "SURFACE",
+    "Act",
+    "BadRequest",
+    "BearerToken",
+    "Client",
+    "ClientCredentials",
+    "Conflict",
+    "Connection",
+    "Credentials",
+    "Forbidden",
+    "NotFound",
+    "PermanentError",
+    "RateLimited",
+    "ServerError",
+    "SystemAccessRequired",
+    "TemperError",
+    "TransientError",
+    "TransportError",
+    "Unauthorized",
+    "__version__",
+    "api_client",
+    "configure",
+    "current_connection",
+    "current_token",
+    "default_backoff",
+    "map_error",
+    "parse_ref",
+    "reset_connection",
+    "with_token",
+]

temper/_validate.py

@@ -0,0 +1,147 @@
+"""What a caller is allowed to hand this package, checked once, at the seam.
+
+Three kinds of value arrive from a caller and then get put somewhere that cannot
+defend itself:
+
+* An ENDPOINT — `configure(base_url=...)`, `ClientCredentials(token_url=...)`. Every
+  API request puts a bearer token on the first; every mint puts the client_secret on
+  the second. So the scheme is not cosmetic, and neither is userinfo: `urlsplit` will
+  happily accept ``https://id:secret@host/`` and the secret then rides in every error
+  message that names the URL.
+* An OPAQUE SECRET or IDENTIFIER — a token, a client id, a device id. These end up in
+  an HTTP header or a form field. The failure that actually happens in the field is
+  not an attack: it is ``TEMPER_M2M_CLIENT_SECRET=$(cat secret.txt)`` keeping the
+  trailing newline, which produces an `invalid_client` no amount of squinting at the
+  secret explains. Rejecting it here names it.
+* A plain non-empty string.
+
+Checked at CONSTRUCTION, not at first use. `Connection` builds its `ApiClient` lazily,
+so a value validated in `_build()` would surface its error on the first API call —
+several layers and possibly several minutes from the `configure()` that caused it.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import SplitResult, urlsplit
+
+#: Hostnames that are the local machine by definition. `.localhost` is reserved for
+#: exactly this by RFC 6761 §6.3, and Docker/CI setups do use `foo.localhost`.
+_LOOPBACK_NAMES = frozenset({"localhost"})
+
+
+def require_str(value: object, name: str) -> str:
+    """A non-empty `str`, and nothing more."""
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty str")
+    return value
+
+
+def require_opaque(value: object, name: str) -> str:
+    """A non-empty `str` safe to put in a header value or a form field, verbatim.
+
+    Rejects rather than strips. A stripped value is a guess about what the caller
+    meant, and the guess is wrong precisely when it matters: a secret with a stray
+    space in the MIDDLE is a different secret, not a formatting slip, and silently
+    sending a trimmed one would turn a clear error into a 401 with no cause attached.
+
+    The whitespace rule is also what keeps a `\\r\\n` out of an `Authorization` or
+    `X-Temper-Device-Id` header. urllib3 v2 rejects such a header itself — but it
+    does so on the request, wrapped in a transport error, with nothing pointing back
+    at the `configure()` or `BearerToken(...)` that introduced it.
+    """
+    text = require_str(value, name)
+    if text != text.strip():
+        raise ValueError(
+            f"{name} has leading or trailing whitespace; "
+            f"strip it at the source (a secret read from a file keeps its newline)"
+        )
+    if any(ch.isspace() for ch in text):
+        raise ValueError(f"{name} must not contain whitespace")
+    # Cc/Cf and friends: never part of a real token, and a `\r\n` here is a header
+    # split. `str.isprintable()` is false for every control character AND for the
+    # separators the whitespace check above already caught.
+    if not text.isprintable():
+        raise ValueError(f"{name} must not contain control characters")
+    return text
+
+
+def require_endpoint(
+    value: object,
+    *,
+    name: str,
+    allow_insecure_http: bool = False,
+) -> SplitResult:
+    """An absolute http(s) origin this package is willing to put a secret on.
+
+    Returns the parsed URL so a caller can reuse the parts rather than re-splitting.
+
+    `http://` is refused off the loopback interface: a bearer token and a
+    client_secret both travel in the clear over it, to anything on the path. Loopback
+    is exempt because that is what a test server and a `temper serve` on your laptop
+    are, and `allow_insecure_http=True` is the deliberate opt-out for the case this
+    cannot see — a private network where TLS terminates elsewhere. It is a keyword a
+    caller has to write, which is the whole point: `verify_ssl=False` used to be a
+    typo away.
+    """
+    text = require_str(value, name)
+    # `urlsplit` SILENTLY strips tab, CR and LF anywhere in the URL (CVE-2019-9740's
+    # fix). Silently is the problem: a `base_url` with an embedded newline would be
+    # accepted here and normalized into something the caller never wrote.
+    if not text.isprintable():
+        raise ValueError(f"{name} must not contain whitespace or control characters")
+
+    try:
+        parts = urlsplit(text)
+    except ValueError as exc:  # a malformed IPv6 literal, principally
+        raise ValueError(f"{name} is not a parseable URL: {text!r}") from exc
+
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        raise ValueError(f"{name} must be an absolute http(s) URL, got {text!r}")
+
+    # `parts.username` is None for `host:port`, so this catches ONLY a real userinfo
+    # section. Refused rather than dropped: a caller who wrote credentials into the
+    # URL meant them to authenticate something, and quietly discarding them would
+    # produce a 401 whose cause is invisible.
+    if parts.username is not None or parts.password is not None:
+        raise ValueError(
+            f"{name} must not carry userinfo (user:password@); "
+            f"pass credentials to ClientCredentials or BearerToken instead"
+        )
+
+    try:
+        # Accessing it is the check: `port` raises for one out of range or not a number.
+        _ = parts.port
+    except ValueError as exc:
+        raise ValueError(f"{name} has an invalid port: {text!r}") from exc
+
+    if parts.query or parts.fragment:
+        raise ValueError(
+            f"{name} must be an origin (optionally with a path prefix), "
+            f"not a URL with a query or fragment: {text!r}"
+        )
+
+    if parts.scheme == "http" and not (allow_insecure_http or is_loopback(parts.hostname)):
+        raise ValueError(
+            f"{name} is plaintext http to a non-loopback host, which would put the "
+            f"bearer token and client_secret on the wire in the clear; use https, or "
+            f"pass allow_insecure_http=True to accept that deliberately"
+        )
+
+    return parts
+
+
+def is_loopback(hostname: str | None) -> bool:
+    """Whether `hostname` names this machine, by literal address or by reserved name.
+
+    `urlsplit.hostname` is already lowercased and already has the brackets stripped
+    off an IPv6 literal, which is what makes `ip_address` the right test here — and
+    it covers the whole 127.0.0.0/8 block, not just 127.0.0.1.
+    """
+    if not hostname:
+        return False
+    try:
+        return ipaddress.ip_address(hostname).is_loopback
+    except ValueError:
+        pass
+    return hostname in _LOOPBACK_NAMES or hostname.endswith(".localhost")

temper/act.py

@@ -0,0 +1,59 @@
+"""Act context for a write. Optional on every call.
+
+The constructor invariant mirrors `ActInput::into_act_context`: Rust's
+`AgentAuthorship.confidence` is non-Option, so authorship without confidence is a 400.
+Rejecting it here is the parse-don't-validate answer — an invalid `Act` cannot be
+constructed, so no call site can send one.
+
+`correlation` and `invocation` are exempt: correlation is provenance, never
+authorship, and an act with no supplied correlation self-roots to its own event id.
+Nothing gates on it, so a client may always omit it.
+
+Ported from `clients/temper-rb/lib/temper/act.rb`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_AUTHORSHIP_FIELDS = ("reasoning", "rationale", "persona", "model")
+
+
+class Act:
+    def __init__(
+        self,
+        *,
+        confidence: Any | None = None,
+        reasoning: str | None = None,
+        rationale: str | None = None,
+        persona: str | None = None,
+        model: str | None = None,
+        correlation: str | None = None,
+        invocation: str | None = None,
+    ) -> None:
+        authorship = {
+            "reasoning": reasoning,
+            "rationale": rationale,
+            "persona": persona,
+            "model": model,
+        }
+        if confidence is None:
+            supplied = [k for k in _AUTHORSHIP_FIELDS if authorship[k] is not None]
+            if supplied:
+                raise ValueError("Act requires `confidence` when supplying " + ", ".join(supplied))
+
+        fields: dict[str, Any] = dict(authorship)
+        fields["confidence"] = None if confidence is None else str(confidence)
+        fields["correlation_id"] = correlation
+        fields["invocation_id"] = invocation
+        # Nils omitted: the server distinguishes an absent key from null.
+        self._fields = {k: v for k, v in fields.items() if v is not None}
+
+    def to_dict(self) -> dict[str, Any]:
+        """The seven `ActInput` wire keys.
+
+        They flatten into ~30 write bodies and onto the query string of
+        `DELETE /api/resources/{id}`, so this is a plain dict rather than a model:
+        both destinations take it as keyword arguments.
+        """
+        return dict(self._fields)

temper/client.py

@@ -0,0 +1,137 @@
+"""The call seam: retry policy, 401 repair, and error translation in one place.
+
+A cheap façade over the process-global connection. Holds a credential and nothing
+else; constructing one does no I/O, so a threaded server can build one per user and a
+worker process can memoize one.
+
+WHY THERE ARE NO PER-ENDPOINT METHODS HERE. The gem hand-writes `Resources`,
+`Contexts`, `CognitiveMaps` because a Ruby caller otherwise passes an untyped hash.
+The generated Python core already answers that: every operation is a typed method
+taking pydantic models, so a hand-written `resources.create(...)` would be a second,
+worse spelling of something already correct — and a place for the two to drift. This
+is the same call temper-ts makes, for the same reason, in `src/client.ts`.
+
+What the generated core does NOT answer is which failures are worth retrying and who
+repairs a dead token. That is what `call()` is.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import urllib3.exceptions
+
+from temper import connection as _connection
+from temper.credentials import Credentials
+from temper.errors import TemperError, TransientError, Unauthorized, map_error
+from temper.generated.api.profile_api import ProfileApi
+from temper.generated.api.search_api import SearchApi
+from temper.generated.api_client import ApiClient
+from temper.generated.exceptions import ApiException
+from temper.generated.models.profile_with_entitlements import ProfileWithEntitlements
+from temper.generated.models.search_params import SearchParams
+from temper.generated.models.search_response import SearchResponse
+
+T = TypeVar("T")
+
+#: 200ms, 400ms — mirroring MAX_ATTEMPTS and the backoff in
+#: crates/temper-client/src/http.rs, and the gem's Client::DEFAULT_BACKOFF.
+MAX_READ_ATTEMPTS = 3
+
+
+def default_backoff(attempt: int) -> None:
+    time.sleep(0.2 * (2 ** (attempt - 1)))
+
+
+class Client:
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        backoff: Callable[[int], None] = default_backoff,
+    ) -> None:
+        self._credentials = credentials
+        self._backoff = backoff
+
+    def call(self, fn: Callable[[ApiClient], T], *, idempotent: bool = False) -> T:
+        """The one seam every call goes through.
+
+        ``idempotent=True``  — a safe method. 5xx and transport failures retry.
+        ``idempotent=False`` — a write. NEVER auto-retried.
+
+        A 401 is repaired once, for reads and writes alike: re-authenticating is not
+        re-submitting. A credential that cannot mint gets its 401 back untouched —
+        `BearerToken.refresh()` raises, and raising here would replace temper's real
+        answer with a message about the client's own plumbing.
+
+        Usage::
+
+            client.call(
+                lambda api: ResourcesApi(api).get_resource(resource_id),
+                idempotent=True,
+            )
+        """
+        attempt = 0
+        reminted = False
+        api = _connection.api_client()
+
+        while True:
+            attempt += 1
+            try:
+                with _connection.with_token(self._credentials.token()):
+                    return fn(api)
+            except (ApiException, urllib3.exceptions.HTTPError) as caught:
+                # Bound outside the `except` so the retry/repair decisions below read as
+                # straight-line code rather than as branches nested in a handler. The
+                # cost is that Python's implicit chaining does not apply out here — hence
+                # the explicit `from raw` on the raise, without which the caller's
+                # traceback would stop at the mapped error and lose the urllib3 or
+                # ApiException frame that says what actually happened.
+                error, raw = map_error(caught), caught
+
+            if self._repair_credentials(error, reminted):
+                reminted = True
+                continue
+
+            if not self._retryable_read(error, idempotent, attempt):
+                raise error from raw
+
+            self._backoff(attempt)
+
+    # -- conveniences the gem also puts on Client itself ----------------------
+
+    def whoami(self) -> ProfileWithEntitlements:
+        """Assert the machine profile resolved, and report what it can reach.
+
+        Authentication is not authorization. A minted M2M token does not even yield a
+        profile on its own: the client_id must already be registered (lookup-or-401 —
+        there is no JIT-create branch), and then, without a cogmap write grant and team
+        membership, every call authenticates cleanly and 403s. Discovering that here
+        beats discovering it on the first write.
+        """
+        return self.call(lambda api: ProfileApi(api).get_profile(), idempotent=True)
+
+    def search(self, query: str, **opts: Any) -> SearchResponse:
+        """`SearchParams` names the field `query`, not `q`."""
+        params = SearchParams(query=query, **opts)
+        return self.call(lambda api: SearchApi(api).search(params), idempotent=True)
+
+    # -- internals -----------------------------------------------------------
+
+    def _repair_credentials(self, error: TemperError, reminted: bool) -> bool:
+        if not isinstance(error, Unauthorized) or reminted:
+            return False
+        if not self._credentials.can_refresh:
+            # The gem reaches the same outcome by letting BearerToken#refresh! raise
+            # its own Unauthorized. Asking first is the same decision made where it
+            # can be read, and it keeps the SERVER's 401 — body and all — as the
+            # error the caller sees.
+            return False
+        self._credentials.refresh()
+        return True
+
+    @staticmethod
+    def _retryable_read(error: TemperError, idempotent: bool, attempt: int) -> bool:
+        return idempotent and isinstance(error, TransientError) and attempt < MAX_READ_ATTEMPTS