cloakapi 0.5.1__py3-none-any.whl

cloakapi/async_client.py

@@ -0,0 +1,704 @@
+"""
+CloakAPI asynchronous client.
+
+Usage::
+
+    import asyncio
+    from cloakapi import AsyncCloakAPI
+
+    async def main():
+        async with AsyncCloakAPI(api_key="cloak_abc123") as client:
+            msg = await client.messages.create(
+                model="claude-sonnet-4-6",
+                messages=[{"role": "user", "content": "Hello!"}],
+            )
+            print(msg.text())
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import inspect
+import logging
+import threading
+import warnings
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import httpx
+
+from ._http import async_request, response_json, validate_response
+from ._pretokenised import fetch_mac_async, proof_headers
+from ._relay import BuiltRelay, build_relay, refuse_plaintext_tier
+from ._request_strings import (
+    bind_tokeniser,
+    restore_arguments,
+    restore_reply_tool_calls,
+    tokenise_body_strings,
+    tokenise_message,
+)
+from .config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    Tier,
+    end_user_header_value,
+    normalise_tier,
+    resolve_api_key,
+    resolve_app_id,
+    resolve_base_url,
+)
+from .coverage import Coverage
+from .engine import engine_available, engine_identity, require_pinned_engine_identity
+from .errors import PlaintextRelayNotSupportedError, ReviewRequiredError
+from .notices import ReviewInfo, SendWarning
+from .pii.tokenizer import TokenMap, detokenize
+from .receipts import receipt_from_headers
+from .resources.admin import AsyncAdminResource
+from .resources.buffer import AsyncBufferResource
+from .resources.chat import AsyncChatResource
+from .resources.detect import AsyncDetectResource
+from .resources.messages import AsyncMessagesResource
+from .resources.models import AsyncModelsResource
+from .resources.receipts import AsyncReceiptsResource
+from .resources.reconstruct import AsyncReconstructResource
+from .resources.tokens import AsyncTokensResource
+from .review import Approved, Prepared, RelayReview, check_review, run_review
+from .surrogate_mode import (
+    SurrogateMode,
+    SurrogateModeReport,
+    coerce_surrogate_mode,
+    resolve_surrogate_mode,
+)
+
+logger = logging.getLogger("cloakapi")
+
+_ReplyT = TypeVar("_ReplyT")
+
+
+class AsyncCloakAPI:
+    """
+    CloakAPI asynchronous client (uses ``httpx.AsyncClient``).
+
+    Same surface area as :class:`~cloakapi.CloakAPI` but all methods are
+    ``async`` and streaming returns ``async for`` iterators.
+
+    Args:
+        api_key: Your CloakAPI key (``cloak_...``). Falls back to
+            ``CLOAKAPI_API_KEY`` env var or ``~/.cloakapi/config.json``.
+        base_url: Gateway base URL. Defaults to ``https://api.cloakapi.io``.
+        timeout: Request timeout in seconds (default 30).
+        max_retries: Maximum retry attempts on transient errors (default 3).
+        http_client: Optional pre-configured ``httpx.AsyncClient`` to use.
+        tokenize: Client-level PII tokenization toggle (overridable per-call).
+            Defaults to ``True`` — privacy-by-default, and the only posture the
+            Level-1-only fail-closed gateway accepts.
+        review: Called before every message/chat request with ``(text, info)``:
+            ``text`` is the exact body that will be sent, ``info`` a
+            :class:`~cloakapi.notices.ReviewInfo` (``state``, ``coverage``,
+            ``warnings``). Return ``True`` to send. Anything else, or no review
+            at all, raises :class:`~cloakapi.errors.ReviewRequiredError` before
+            any network call. ``lambda text, info: True`` is the one-liner for
+            server-side use. For your own review screen use the step form:
+            ``prepare`` -> ``approve`` -> ``send``.
+        review_callback: Deprecated 0.4.x form of ``review``; receives a
+            :class:`~cloakapi.review.RelayReview` (method, URL, body bytes,
+            headers) and must return ``True``. Removed in 0.6.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        tokenize: bool = True,
+        tier: Tier = "balanced",
+        seed_hex: str | None = None,
+        app_id: str | None = None,
+        end_user_secret: str | None = None,
+        surrogate_mode: SurrogateMode | None = None,
+        review_callback: Callable[[RelayReview], Any] | None = None,
+        review: Callable[[str, ReviewInfo], Any] | None = None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        # ADR-0015 ecosystem attribution — opaque app/site slug → X-Cloak-App-Id
+        # on every relay call. Defaults from CLOAK_APP_ID env; None → omitted.
+        self.app_id = resolve_app_id(app_id)
+        # HMAC secret for client-side end-user tokenisation. None uses the
+        # API key, so rotating the key rotates the pseudonym; set this to pin one
+        # end user to one token across rotations. Must match the other SDKs'
+        # end_user_secret for a cross-language join to line up.
+        self._end_user_secret = end_user_secret or None
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.tokenize = tokenize
+        self.tier: Tier = normalise_tier(tier)
+        self.seed_hex = seed_hex
+        # `review(text, info)` is the form every CloakAPI SDK shares. The
+        # 0.4.x `review_callback(request)` keeps working for one minor version.
+        self.review = review
+        self.review_callback = review_callback
+        if review_callback is not None and review is None:
+            warnings.warn(
+                "review_callback is deprecated; pass review=(text, info) -> bool instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        # SURROGATE MODE — see CloakAPI.__init__ in client.py for the full
+        # rationale. Explicit argument RESOLVES (bad literal raises); otherwise
+        # the legacy `tier` is COERCED onto a protected mode.
+        self.surrogate_mode: SurrogateMode = (
+            resolve_surrogate_mode(surrogate_mode)
+            if surrogate_mode is not None
+            else coerce_surrogate_mode(self.tier)
+        )
+        self._token_map: TokenMap = {}
+        # THE CONVERSATION LEDGER — its presence puts every tokenise call in
+        # CONVERSATION scope. RE-IDENTIFICATION MATERIAL: client-side only,
+        # never egressed/logged/receipted.
+        self._bindings: dict[str, Any] = {}
+        # Serialises "read the ledger, detect, write the ledger" per string, so
+        # threads that share this client cannot lose each other's stand-ins.
+        self._tokenise_lock = threading.RLock()
+        self._bindings_revision = 0
+        self._last_surrogate_mode: SurrogateModeReport | None = None
+        self._last_coverage: Coverage | None = None
+        self._last_warnings: tuple[SendWarning, ...] = ()
+        self._last_value_not_replaced = False
+        self._last_receipt: dict[str, Any] | None = None
+        self._pending: dict[int, dict[str, Any]] = {}
+        self._owns_client = http_client is None
+        self._http_client: httpx.AsyncClient = http_client or httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout,
+            # The only permitted HTTP base is loopback. Do not let an
+            # environment proxy receive its bearer Authorization header.
+            mounts={"http://": httpx.AsyncHTTPTransport(trust_env=False)},
+        )
+        # Resource namespaces
+        self.messages = AsyncMessagesResource(self)
+        self.chat = AsyncChatResource(self)
+        self.buffer = AsyncBufferResource(self)
+        self.admin = AsyncAdminResource(self)
+        self.models = AsyncModelsResource(self)
+        self.tokens = AsyncTokensResource(self)
+        self.receipts = AsyncReceiptsResource(self)
+        self.reconstruct = AsyncReconstructResource(self)
+        self.detect = AsyncDetectResource(self)
+
+    # ── HTTP helpers ─────────────────────────────────────────────────────────
+
+    @property
+    def base_url(self) -> str:
+        """The gateway origin fixed when this client was constructed."""
+        return self._base_url
+
+    def _require_egress_engine_identity(self) -> None:
+        """Defer identity attestation until tokenisation coverage is known."""
+        return None
+
+    async def _unsafe_raw_async_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        content: bytes | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Send an unreviewed HTTP request. Internal plumbing only; unsafe for caller data."""
+        return await async_request(
+            self._http_client,
+            method,
+            path,
+            self.api_key,
+            base_url=self._base_url,
+            body=body,
+            content=content,
+            extra_headers=extra_headers,
+            max_retries=self.max_retries,
+            timeout=self.timeout,
+        )
+
+    async def _prepare_relay(
+        self,
+        body: dict[str, Any],
+        extra_headers: dict[str, str],
+        should_tokenize: bool,
+        *,
+        method: str = "POST",
+        path: str = "/api/v1/messages",
+        token_state: dict[str, Any] | None = None,
+        call_state: dict[str, Any] | None = None,
+    ) -> tuple[bytes, dict[str, str]]:
+        """Finalise one relay request: body bytes, review, proof.
+
+        Serialises the assembled body ONCE (the exact bytes that will leave),
+        shows them to the caller's review, then mints the per-body MAC over
+        those bytes from ``POST /api/v1/pretokenised/mac`` and attaches the
+        proof headers the gateway checks::
+
+            X-Cloak-Pretokenised: 1
+            X-Cloak-Client-MAC:  <HMAC over these exact bytes>
+            X-CloakAPI-Routing:  client
+
+        Returns ``(content, headers)``; the caller MUST send ``content``
+        verbatim.
+
+        * Reduced coverage never stops the request. It is stated in
+          ``X-Cloak-Coverage`` and ``X-CloakAPI-Tokenized``, shown to the
+          reviewer, and the request claims no engine identity.
+        * The MAC is fetched on every lane, with the caller's own HTTP client.
+          It proves which bytes this key holder prepared; it says nothing about
+          which engine ran. If it cannot be obtained the request is not sent
+          and the gateway or network error is raised.
+        * Plaintext relay does not exist (``tier='off'`` is refused).
+        """
+        bindings_revision = self._bindings_revision
+        try:
+            own_state = call_state if call_state is not None else token_state
+            built = self._build_relay(
+                body, extra_headers, should_tokenize, method=method, path=path, state=own_state
+            )
+            if own_state is not None:
+                own_state["built"] = built  # the reply is annotated from this, not from "latest"
+            answer = run_review(self, built)
+            if inspect.isawaitable(answer):
+                try:
+                    answer = await answer
+                except Exception:
+                    raise ReviewRequiredError() from None
+            check_review(answer)
+            await self._attach_proof(built)
+            return built.content, built.headers
+        except BaseException:
+            if token_state is not None and self._bindings_revision == bindings_revision:
+                self._bindings.clear()
+                self._bindings.update(copy.deepcopy(token_state["bindings_before"]))
+                self._bindings_revision += 1
+            raise
+
+    def _build_relay(
+        self,
+        body: dict[str, Any],
+        extra_headers: dict[str, str],
+        should_tokenize: bool,
+        *,
+        method: str = "POST",
+        path: str = "/api/v1/messages",
+        state: dict[str, Any] | None = None,
+    ) -> BuiltRelay:
+        """Body bytes, headers and notices of one request. No review, no network."""
+        return build_relay(
+            self,
+            body,
+            extra_headers,
+            should_tokenize,
+            method=method,
+            path=path,
+            engine_available=engine_available,
+            require_pinned_engine_identity=require_pinned_engine_identity,
+            state=state,
+        )
+
+    async def _attach_proof(self, built: BuiltRelay) -> None:
+        """Mint the MAC over the reviewed bytes and attach the proof headers."""
+        refuse_plaintext_tier(self)
+        mac = await fetch_mac_async(
+            self._http_client,
+            self.api_key,
+            built.content,
+            base_url=self._base_url,
+            max_retries=self.max_retries,
+            timeout=self.timeout,
+        )
+        built.headers.update(proof_headers(mac))
+
+    # ── step form: prepare -> approve -> send ────────────────────────────────
+
+    def _register_prepared(
+        self, built: BuiltRelay, *, kind: str, token_map: dict[str, str]
+    ) -> Prepared:
+        prepared = Prepared(
+            text=built.text,
+            coverage=built.coverage.value,
+            warnings=built.warnings,
+            state=built.state,
+            method=built.method,
+            url=built.url,
+        )
+        self._pending[id(prepared._handle)] = {
+            "prepared": prepared,
+            "built": built,
+            "kind": kind,
+            "token_map": dict(token_map),
+            "approved": None,
+        }
+        return prepared
+
+    def _prepare_step(
+        self,
+        body: dict[str, Any],
+        extra_headers: dict[str, str],
+        should_tokenize: bool,
+        *,
+        path: str,
+        kind: str,
+        state: dict[str, Any],
+    ) -> Prepared:
+        """``prepare()``: build the request and hand it back for review."""
+        bindings_revision = self._bindings_revision
+        try:
+            built = self._build_relay(
+                body, extra_headers, should_tokenize, method="POST", path=path, state=state
+            )
+        except BaseException:
+            if self._bindings_revision == bindings_revision:
+                self._bindings.clear()
+                self._bindings.update(copy.deepcopy(state["bindings_before"]))
+                self._bindings_revision += 1
+            raise
+        return self._register_prepared(built, kind=kind, token_map=state["token_map"])
+
+    def approve(self, prepared: Prepared) -> Approved:
+        """Record that the text of ``prepared`` was reviewed and may be sent.
+
+        Returns the object :meth:`send` requires. Approving something this
+        client did not prepare is ``review_required``.
+        """
+        entry = self._pending.get(id(getattr(prepared, "_handle", None)))
+        if entry is None or entry["prepared"] is not prepared:
+            raise ReviewRequiredError()
+        approved = Approved(prepared=prepared, text=prepared.text)
+        entry["approved"] = approved
+        return approved
+
+    async def send(self, approved: Approved) -> Any:
+        """Send a request that :meth:`approve` approved, exactly as it was shown.
+
+        Anything else (a prepared request that was not approved, an object
+        built by hand, text that differs by one byte, a second send of the same
+        approval) raises :class:`~cloakapi.errors.ReviewRequiredError` before
+        any network call.
+        """
+        prepared = getattr(approved, "prepared", None)
+        entry = self._pending.get(id(getattr(prepared, "_handle", None)))
+        if (
+            not isinstance(approved, Approved)
+            or entry is None
+            or entry["approved"] is not approved
+            or entry["prepared"] is not prepared
+        ):
+            raise ReviewRequiredError()
+        built: BuiltRelay = entry["built"]
+        if approved.text.encode("utf-8") != built.content or prepared.text != approved.text:
+            raise ReviewRequiredError()
+        del self._pending[id(prepared._handle)]
+        # A send that fails must not leave an earlier reply's receipt behind.
+        self._last_receipt = None
+        await self._attach_proof(built)
+        response = await self._unsafe_raw_async_request(
+            built.method, built.path, content=built.content, extra_headers=built.headers
+        )
+        self._record_receipt(response, built)
+        data = response_json(response)
+        from .types import ChatCompletion, Message
+
+        if entry["kind"] == "chat":
+            data = self._detokenize_chat(data, entry["token_map"])
+            return self._annotate(
+                validate_response(data, ChatCompletion, endpoint=built.path), built
+            )
+        data = self._detokenize_message(data, entry["token_map"])
+        return self._annotate(validate_response(data, Message, endpoint=built.path), built)
+
+    def _annotate(self, result: _ReplyT, built: BuiltRelay | None = None) -> _ReplyT:
+        """Put this send's coverage and notices on the reply object."""
+        coverage = built.coverage if built is not None else self._last_coverage
+        warnings = built.warnings if built is not None else self._last_warnings
+        with contextlib.suppress(Exception):
+            reply: Any = result
+            reply.coverage = coverage.value if coverage is not None else None
+            reply.warnings = list(warnings)
+            reply.receipt = built.receipt if built is not None else self._last_receipt
+        return result
+
+    def _record_receipt(self, response: Any, built: BuiltRelay | None = None) -> None:
+        """Keep the receipt the gateway returned with this reply, if any.
+
+        On the request itself (it is put on the reply as ``reply.receipt``) and
+        as ``last_receipt``, which is "the most recent reply on this client".
+        """
+        receipt = receipt_from_headers(getattr(response, "headers", None))
+        if built is not None:
+            built.receipt = receipt
+        self._last_receipt = receipt
+
+    @property
+    def last_receipt(self) -> dict[str, Any] | None:
+        """The signed receipt of the most recent completed non-streaming call.
+
+        The decoded ``X-CloakAPI-Receipt-V2`` response header, or ``None`` when
+        the gateway returned none (it does not for every call), and ``None``
+        after a streaming call or a call that failed. Each reply also carries
+        its own as ``reply.receipt``; use that when requests overlap. Verify it
+        without a network round trip with
+        ``client.receipts.verify_offline(receipt, jwks=...)``.
+        """
+        return self._last_receipt
+
+    @property
+    def last_warnings(self) -> tuple[SendWarning, ...]:
+        """Notices of the most recently prepared request (empty when none)."""
+        return self._last_warnings
+
+    # ── PII helpers (identical logic to sync client) ──────────────────────────
+
+    def _prepare_messages(
+        self,
+        messages: list[dict[str, Any]],
+        should_tokenize: bool,
+        *,
+        return_state: bool = False,
+    ) -> Any:
+        extra_headers: dict[str, str] = {}
+        # ADR-0015 — attribution app slug rides on EVERY relay call (all tiers).
+        if self.app_id:
+            extra_headers["X-Cloak-App-Id"] = self.app_id
+        if not should_tokenize:
+            raise PlaintextRelayNotSupportedError(
+                "tokenize=False is not supported for request bodies; enable on-device tokenization."
+            )
+
+        # Every text channel of a message, not only a `str` content — one walker
+        # shared with the sync client (see cloakapi._request_strings).
+        # token_map is per call (the reply is restored from that call only).
+        # bindings is the conversation ledger and must be the same object next turn.
+        state: dict[str, Any] = {
+            "token_map": {},
+            "bindings": self._bindings,
+            "bindings_before": copy.deepcopy(self._bindings),
+            "coverage": None,
+        }
+        self._last_coverage = None
+        self._last_value_not_replaced = False
+        # A receipt belongs to one reply. A call that ends without one (a
+        # stream, an error) must not leave the previous call's receipt behind.
+        self._last_receipt = None
+        tok = bind_tokeniser(self, state)
+        try:
+            processed = [tokenise_message(msg, tok) for msg in messages]
+        except BaseException:
+            self._bindings.clear()
+            self._bindings.update(copy.deepcopy(state["bindings_before"]))
+            self._bindings_revision += 1
+            raise
+
+        extra_headers["X-CloakAPI-Tokenized"] = "true"  # coverage is added once it is final
+        # Read from this request's own state: the client attributes are "the
+        # latest request" and another thread may have reset them meanwhile.
+        coverage = state.get("coverage") or Coverage.FULL
+        extra_headers["X-Cloak-Coverage"] = coverage.value
+        last_mode = state.get("surrogate_mode") or self._last_surrogate_mode
+        actual_mode = getattr(last_mode, "mode", last_mode)
+        extra_headers["X-CloakAPI-Mode"] = (
+            "max" if coverage is Coverage.RULES_ONLY and actual_mode == "max" else self.tier
+        )
+        if coverage is not Coverage.RULES_ONLY:
+            ident = engine_identity()
+            if isinstance(ident, dict) and ident.get("version"):
+                extra_headers["X-Cloak-Engine-Version"] = ident["version"]
+                if ident.get("hash"):
+                    extra_headers["X-Cloak-Engine-Hash"] = ident["hash"]
+        if return_state:
+            return processed, extra_headers, state
+        return processed, extra_headers
+
+    def _prepare_body_strings(
+        self, body: dict[str, Any], should_tokenize: bool, state: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Async twin of :meth:`CloakAPI._prepare_body_strings` for all body text slots."""
+        if not should_tokenize:
+            return body
+        try:
+            return tokenise_body_strings(body, bind_tokeniser(self, state))
+        except BaseException:
+            if state is not None:
+                self._bindings.clear()
+                self._bindings.update(copy.deepcopy(state["bindings_before"]))
+                self._bindings_revision += 1
+            raise
+
+    @property
+    def last_surrogate_mode(self) -> SurrogateModeReport | None:
+        """What the most recent outbound tokenise pass ACTUALLY did (mode +
+        continuity scope). Feed ``.continuity`` into
+        :func:`cloakapi.disclosure.with_disclosure`. ``None`` before the first
+        tokenised call."""
+        return self._last_surrogate_mode
+
+    @property
+    def last_coverage(self) -> Coverage | None:
+        """Local detection coverage applied to the most recently prepared relay."""
+        return self._last_coverage
+
+    def _end_user_header(self, end_user: str | None) -> dict[str, str]:
+        """TOKENISE, NEVER REFUSE. Identical
+        to the sync client: a shape-valid non-PII token goes out exactly as
+        supplied, everything else is tokenised HERE before the network, and the
+        header is omitted only when there is nothing to attribute."""
+        value = end_user_header_value(end_user, self._end_user_secret or self.api_key)
+        return {"X-Cloak-End-User": value} if value else {}
+
+    def _prepare_attachments(
+        self,
+        attachments: list[Any],
+        names: list[str] | None = None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, str], bool]:
+        """Refuse convenience attachments until the caller can review their text."""
+        from .attachments import ATTACHMENT_REVIEW_MESSAGE, AttachmentReviewRequiredError
+
+        raise AttachmentReviewRequiredError(ATTACHMENT_REVIEW_MESSAGE)
+
+    def _detokenize_message(self, data: dict[str, Any], token_map: TokenMap | None = None) -> dict[str, Any]:
+        token_map = self._token_map if token_map is None else token_map
+        if not token_map or not isinstance(data, dict):
+            return data
+        content = data.get("content")
+        if isinstance(content, list):
+            new_content = []
+            for block in content:
+                if isinstance(block, dict) and isinstance(block.get("text"), str):
+                    block = {**block, "text": detokenize(block["text"], token_map)}
+                # A tool call the model wrote: its argument VALUES may hold
+                # stand-ins, and the caller's tool must receive the real values.
+                if isinstance(block, dict) and isinstance(block.get("input"), (dict, list)):
+                    restored = restore_arguments(block["input"], token_map)
+                    if restored is not block["input"]:
+                        block = {**block, "input": restored}
+                new_content.append(block)
+            data = {**data, "content": new_content}
+        return data
+
+    def _detokenize_chat(self, data: dict[str, Any], token_map: TokenMap | None = None) -> dict[str, Any]:
+        token_map = self._token_map if token_map is None else token_map
+        if not token_map or not isinstance(data, dict):
+            return data
+        choices = data.get("choices")
+        if not isinstance(choices, list):
+            return data
+        new_choices = []
+        for choice in choices:
+            if not isinstance(choice, dict):
+                new_choices.append(choice)
+                continue
+            msg = choice.get("message")
+            if isinstance(msg, dict) and isinstance(msg.get("content"), str):
+                msg = {**msg, "content": detokenize(msg["content"], token_map)}
+                choice = {**choice, "message": msg}
+            if isinstance(msg, dict):
+                restored_msg = restore_reply_tool_calls(msg, token_map)
+                if restored_msg is not msg:
+                    msg = restored_msg
+                    choice = {**choice, "message": msg}
+            new_choices.append(choice)
+        return {**data, "choices": new_choices}
+
+    def _detokenize_stream_event(self, event: Any) -> Any:
+        if not self._token_map:
+            return event
+        from .types import ContentBlockDelta
+
+        if isinstance(event, ContentBlockDelta):
+            delta = event.delta
+            if isinstance(delta, dict) and isinstance(delta.get("text"), str):
+                new_delta = {**delta, "text": detokenize(delta["text"], self._token_map)}
+                return ContentBlockDelta(type=event.type, index=event.index, delta=new_delta)
+        return event
+
+    def _detokenize_chat_chunk(self, chunk: Any) -> Any:
+        if not self._token_map:
+            return chunk
+        from .types import ChatCompletionChunk, ChunkDelta, StreamChoice
+
+        new_choices = []
+        for choice in chunk.choices:
+            delta = choice.delta
+            if isinstance(delta.content, str):
+                new_delta = ChunkDelta(
+                    role=delta.role,
+                    content=detokenize(delta.content, self._token_map),
+                )
+                choice = StreamChoice(
+                    index=choice.index,
+                    delta=new_delta,
+                    finish_reason=choice.finish_reason,
+                )
+            new_choices.append(choice)
+        return ChatCompletionChunk(
+            id=chunk.id,
+            object=chunk.object,
+            created=chunk.created,
+            model=chunk.model,
+            choices=new_choices,
+            usage=chunk.usage,
+        )
+
+    def _new_stream_detokenizer(self, token_map: TokenMap | None = None) -> Any:
+        from .pii.tokenizer import StreamDetokenizer
+
+        return StreamDetokenizer((self._token_map if token_map is None else token_map) or {})
+
+    async def adetok_anthropic_stream(self, events: Any, token_map: TokenMap | None = None) -> Any:
+        """Boundary-safe Anthropic stream. See :mod:`cloakapi._stream_detok`."""
+        from ._stream_detok import adetok_stream, anthropic_shape
+
+        token_map = self._token_map if token_map is None else token_map
+        if not token_map:
+            async for e in events:
+                yield e
+            return
+        async for e in adetok_stream(events, self._new_stream_detokenizer(token_map), anthropic_shape()):
+            yield e
+
+    async def adetok_openai_stream(self, chunks: Any, token_map: TokenMap | None = None) -> Any:
+        """Boundary-safe OpenAI stream. See :mod:`cloakapi._stream_detok`."""
+        from ._stream_detok import adetok_stream, openai_shape
+
+        token_map = self._token_map if token_map is None else token_map
+        if not token_map:
+            async for c in chunks:
+                yield c
+            return
+        async for c in adetok_stream(chunks, self._new_stream_detokenizer(token_map), openai_shape()):
+            yield c
+
+    # ── Context manager ──────────────────────────────────────────────────────
+
+    async def __aenter__(self) -> AsyncCloakAPI:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    def clear_token_map(self) -> None:
+        """Clear the PII token map.
+
+        Call this between independent conversations to prevent token accumulation
+        from leaking context across sessions. Long-lived clients that tokenize
+        many requests should call this periodically for privacy hygiene.
+        """
+        self._token_map = {}
+        self._bindings = {}
+        self._bindings_revision += 1
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client (only if we created it)."""
+        if self._owns_client:
+            await self._http_client.aclose()