idside 0.1.0.dev0__py3-none-any.whl

idside/options.py

@@ -0,0 +1,297 @@
+# Patents: https://sdk.idside.eu/patents
+# This software may be covered by the patents and applications listed there.
+
+"""The consent options an app can actually put to its users.
+
+A developer wrapping OpenAI and Gemini needs to know what to render in their
+consent UI, and the honest answer depends on which providers they wrap. This
+module computes it from the shared catalogue, offline, with no network call.
+
+The rule that shapes everything here:
+
+    A question reaches an end user only if at least one of the app's providers
+    can enforce it PER REQUEST.
+
+An account-level control lives on the developer's API key and applies to all of
+their users at once. Asking one person about it would manufacture the appearance
+of a choice nobody has — two users answering differently would be treated
+identically. Those become *disclosures* instead: facts about how this app is
+configured, which the developer must be able to state and which the ledger
+records, but which no consent dialog may present as a choice.
+
+The exception is `routable`: an account-level control becomes a genuine per-user
+one when the developer provisions several credentials with different privacy
+postures, because the SDK can then pick the credential matching each answer.
+That is the only route by which training opt-out can ever be honoured per user —
+no provider exposes it as a request parameter.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from functools import cache, lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+__all__ = [
+    "ConsentOption",
+    "Disclosure",
+    "catalogue",
+    "decidable_options",
+    "disclosures",
+]
+
+_CATALOGUE_PATH = Path(__file__).resolve().parent / "consent-options.json"
+_PROVIDER_DIR = Path(__file__).resolve().parent / "providers"
+#: The only names that may ever become a path. See _raw_enforcement.
+_KNOWN_PROVIDERS = frozenset(p.stem for p in _PROVIDER_DIR.glob("*.json"))
+
+EnforcementLevel = Literal[
+    "enforced", "contractual", "account", "absent", "unsupported"
+]
+
+#: The levels at which no control exists, whatever the reason.
+_NO_CONTROL = frozenset({"absent", "unsupported"})
+
+
+@dataclass(frozen=True)
+class ConsentOption:
+    """One question, ready to render."""
+
+    name: str
+    group: str
+    label_en: str
+    label_fr: str
+    description_en: str
+    description_fr: str
+    default: bool
+    legal_basis: str
+    gdpr: str
+    #: Which of the app's providers can honour it, and how.
+    enforced_by: tuple[str, ...] = ()
+    #: Providers that will honour it by *routing* the call to the credential
+    #: carrying that posture, rather than by a request parameter. The answer is
+    #: as real to the user either way; the mechanism differs, and a consent UI
+    #: that explains itself may want to say which.
+    routed_by: tuple[str, ...] = ()
+
+    def label(self, locale: str = "en") -> str:
+        return self.label_fr if locale.startswith("fr") else self.label_en
+
+    def description(self, locale: str = "en") -> str:
+        return self.description_fr if locale.startswith("fr") else self.description_en
+
+
+@dataclass(frozen=True)
+class Disclosure:
+    """Something the user cannot decide, and the developer must not hide.
+
+    ``guaranteed`` — true for everyone already, and in the user's favour: the
+    terms of every provider that answers it rule the processing out
+    (``contractual`` and ``protective``). Terms that allow or impose it are no
+    guarantee, and neither is one provider among several whose terms do.
+    ``beyond_user_control`` — the app's own configuration decides, or the
+    provider's terms do (``contractual`` terms that allow or impose it, or leave
+    it to the developer's organization): no answer in a dialog could change it.
+    If it is also ``routable``, the developer *could* give their users the choice
+    by provisioning a second credential; until they do, they are making it for
+    them.
+    ``not_offered`` — no control for it is reachable through the endpoints the
+    descriptors wrap, whether the processing is ``absent`` from the API or
+    ``unsupported`` there. Nobody decided anything; there is nothing to decide.
+    Saying "your app configured this" about a feature the API does not have
+    would be plainly false.
+    """
+
+    option: ConsentOption
+    kind: Literal["guaranteed", "beyond_user_control", "not_offered"]
+    by_provider: dict[str, str]
+    routable_from: tuple[str, ...] = ()
+
+    @property
+    def routable(self) -> bool:
+        return bool(self.routable_from)
+
+
+@lru_cache(maxsize=1)
+def catalogue() -> dict[str, Any]:
+    """The shared option catalogue, as shipped with this package."""
+    loaded: dict[str, Any] = json.loads(_CATALOGUE_PATH.read_text(encoding="utf-8"))
+    return loaded
+
+
+def _option(
+    raw: dict[str, Any],
+    enforced_by: tuple[str, ...] = (),
+    routed_by: tuple[str, ...] = (),
+) -> ConsentOption:
+    return ConsentOption(
+        name=raw["name"],
+        group=raw["group"],
+        label_en=raw["label_en"],
+        label_fr=raw["label_fr"],
+        description_en=raw["description_en"],
+        description_fr=raw["description_fr"],
+        default=raw["default"],
+        legal_basis=raw["legal_basis"],
+        gdpr=raw["gdpr"],
+        enforced_by=enforced_by,
+        routed_by=routed_by,
+    )
+
+
+#: A posture nobody can be routed away from is not a choice. One credential is
+#: the app's single posture, whatever it is labelled; it takes a second for two
+#: users to be treated differently.
+_MIN_POSTURES_FOR_A_CHOICE = 2
+
+
+def _routing_providers(routed: Mapping[str, Sequence[str]] | None) -> frozenset[str]:
+    """The providers where the developer really can send two users two ways."""
+    if not routed:
+        return frozenset()
+    return frozenset(
+        provider
+        for provider, postures in routed.items()
+        if len(set(postures)) >= _MIN_POSTURES_FOR_A_CHOICE
+    )
+
+
+def _enforcement(providers: list[str] | tuple[str, ...]) -> dict[str, dict[str, Any]]:
+    from idside.providers import load_descriptors
+
+    descriptors = load_descriptors()
+    known = {}
+    for name in providers:
+        descriptor = descriptors.get(name)
+        if descriptor is None:
+            continue
+        known[name] = getattr(descriptor, "enforcement", None) or _raw_enforcement(name)
+    return known
+
+
+@cache
+def _raw_enforcement(provider: str) -> dict[str, Any]:
+    """Read the enforcement map straight from the bundled descriptor.
+
+    The runtime ``ProviderDescriptor`` deliberately carries only what the SDK
+    needs to make a call. The enforcement map is documentation for humans and
+    input for a consent UI, so it is read here rather than widening that class.
+
+    The name is checked against the bundled descriptors before it ever reaches a
+    path. ``decidable_options`` is public API taking caller-supplied strings, and
+    interpolating one into a filesystem path made
+    ``decidable_options(["../../../etc/passwd"])`` read and parse an arbitrary
+    file whose contents then flowed into the returned options.
+    """
+    if provider not in _KNOWN_PROVIDERS:
+        return {}
+
+    path = _PROVIDER_DIR / f"{provider}.json"
+    if not path.exists():
+        return {}
+    raw: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    enforcement: dict[str, Any] = raw.get("enforcement", {})
+    return enforcement
+
+
+def decidable_options(
+    providers: list[str] | tuple[str, ...],
+    routed: Mapping[str, Sequence[str]] | None = None,
+) -> list[ConsentOption]:
+    """The questions this app may actually put to a user, in catalogue order.
+
+    Ordered by the catalogue rather than by provider, so the dialog never
+    depends on which client happened to be wrapped first, and each question is
+    asked once however many providers share it.
+
+    ``routed`` maps a provider to the posture labels the app provisioned for it
+    — the keys of the ``credentials=`` mapping given to ``consent.wrap()``. An
+    account-level option marked ``routable`` in the descriptor becomes a real
+    question for that provider once there are **two** of them, because two users
+    answering differently can then be treated differently. With one, the app has
+    one posture and asking would manufacture a choice nobody has.
+    """
+    levels = _enforcement(providers)
+    routing = _routing_providers(routed)
+    options = []
+
+    for raw in catalogue()["options"]:
+        enforced_by = tuple(
+            name
+            for name, enforcement in levels.items()
+            if enforcement.get(raw["name"], {}).get("level") == "enforced"
+        )
+        routed_by = tuple(
+            name
+            for name, enforcement in levels.items()
+            if name in routing
+            and name not in enforced_by
+            and enforcement.get(raw["name"], {}).get("routable")
+        )
+        if enforced_by or routed_by:
+            options.append(_option(raw, enforced_by, routed_by))
+
+    return options
+
+
+def _kind_for(
+    entries: list[dict[str, Any]],
+) -> Literal["guaranteed", "beyond_user_control", "not_offered"]:
+    """Mirrors `kindFor` in the Node SDK — these values cross SDK boundaries.
+
+    ``contractual`` alone says the terms decide, not which way: it used to be
+    read as a guarantee, which called Anthropic's review of flagged content and
+    OpenAI's "unless the org opts in" guaranteed to the user.
+    """
+    if all(
+        entry["level"] == "contractual" and entry.get("protective") is True
+        for entry in entries
+    ):
+        return "guaranteed"
+    if {entry["level"] for entry in entries} <= _NO_CONTROL:
+        return "not_offered"
+    return "beyond_user_control"
+
+
+def disclosures(
+    providers: list[str] | tuple[str, ...],
+    routed: Mapping[str, Sequence[str]] | None = None,
+) -> list[Disclosure]:
+    """What the user cannot decide — stated, never asked.
+
+    ``routed`` is the same argument :func:`decidable_options` takes, and moves
+    the same options: anything the app can now route on becomes a question, so
+    it stops being a disclosure. Passing it to one and not the other would say
+    two contradictory things about the same option.
+    """
+    levels = _enforcement(providers)
+    asked = {option.name for option in decidable_options(providers, routed)}
+    found = []
+
+    for raw in catalogue()["options"]:
+        if raw["name"] in asked:
+            continue
+
+        entries = {
+            name: enforcement[raw["name"]]
+            for name, enforcement in levels.items()
+            if enforcement.get(raw["name"], {}).get("level")
+        }
+        if not entries:
+            continue
+
+        found.append(
+            Disclosure(
+                option=_option(raw),
+                kind=_kind_for(list(entries.values())),
+                by_provider={name: entry["level"] for name, entry in entries.items()},
+                routable_from=tuple(
+                    name for name, entry in entries.items() if entry.get("routable")
+                ),
+            )
+        )
+
+    return found

idside/providers/__init__.py

@@ -0,0 +1,252 @@
+# Patents: https://sdk.idside.eu/patents
+# This software may be covered by the patents and applications listed there.
+
+"""Provider descriptors and their auto-loading from bundled JSON files.
+
+A descriptor declares the *mechanics* of a provider (which calls to intercept,
+where to inject forced params, which header carries the ACT token). The *policy*
+(which params to force for a given consent state) is decided by the cloud and
+returned as ``params_forced`` — it does not live here.
+
+Add a standard provider by dropping a JSON file in this package; no Python needed.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any
+
+DEFAULT_CONSENT_HEADER = "X-AI-Consent-Token"
+
+__all__ = [
+    "CallSite",
+    "CredentialRouting",
+    "ProviderDescriptor",
+    "ToolField",
+    "load_descriptors",
+]
+
+
+@dataclass(frozen=True)
+class CredentialRouting:
+    """How this provider lets one app hold several privacy postures at once.
+
+    The privacy posture (does this traffic train the model, is it retained, in
+    which region) is not a request parameter anywhere — it is a property of the
+    credential. ``unit`` names what the credential selects: a *project* at
+    OpenAI and Gemini, a *workspace* at Anthropic, an *organisation* at Mistral.
+
+    ``header`` is the per-request header that selects it, when the provider
+    validates one — only OpenAI does (``OpenAI-Project``). Without it, switching
+    posture means switching client, because a key is chosen at construction.
+
+    ``header_value_pattern`` is checked before any value reaches an outgoing
+    request. It keeps CR/LF out of a header, and refuses a value of the wrong
+    kind: an OpenAI project id is ``proj_…`` where an API key is ``sk-…``, and
+    the developer who pastes the second must be stopped before the secret
+    leaves the process.
+    """
+
+    header: str | None = None
+    header_value_pattern: str | None = None
+    unit: str = "credential"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CredentialRouting:
+        return cls(
+            header=data.get("header"),
+            header_value_pattern=data.get("header_value_pattern"),
+            unit=data.get("unit") or "credential",
+        )
+
+
+@dataclass(frozen=True)
+class ToolField:
+    """One argument through which a call can hand the model a tool.
+
+    A ``tools`` constraint is only as wide as what the SDK reads. Reading the
+    provider's ``tools`` key alone let ``functions``, ``web_search_options``, a
+    Mistral agent, a Gemini cache or a stored OpenAI conversation carry tools
+    straight past a refusal — so each call site names every such argument.
+
+    ``kind`` decides how a refusal is applied:
+
+    - ``definitions`` — a list of tool definitions. An empty list carries none;
+      under ``strip`` the key is removed.
+    - ``enabler`` — any present, non-null value can bring tools with it: an
+      object switching a hosted tool on, or a reference to a server-side object
+      the SDK cannot see into. Removing it would change what the call means, so
+      it is refused under ``strip`` as under ``refuse``.
+    - ``input_items`` — an array whose items of the listed ``item_types`` carry
+      tool definitions. Refused under both, for the same reason.
+
+    ``path`` is in the Python client's spelling; the descriptor's ``js_path``
+    belongs to the other SDK and is not read here.
+    """
+
+    path: tuple[str, ...]
+    kind: str
+    item_types: frozenset[str] = frozenset()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolField:
+        return cls(
+            path=tuple(data["path"]),
+            kind=data["kind"],
+            item_types=frozenset(data.get("item_types", ())),
+        )
+
+
+@dataclass(frozen=True)
+class CallSite:
+    """One endpoint to intercept, and what may be forced *on that endpoint*.
+
+    A provider's endpoints do not accept the same parameters. OpenAI's
+    ``background`` exists on ``/v1/responses`` and nowhere else, so a
+    provider-wide allowlist could only ever be the intersection (losing the
+    lever) or the union (breaking ``chat.completions`` for exactly the users who
+    opted out). Hence one allowlist per site.
+
+    ``id`` is the stable, language-neutral name sent to the cloud as
+    ``call_site``. It is written in the Python client's spelling because the
+    descriptor is shared: the JS client may call the same endpoint something else
+    (``generateContent`` vs ``generate_content``), and one endpoint must have one
+    name on the wire.
+    """
+
+    id: str
+    path: tuple[str, ...]
+    #: Extra method names on the SAME target object that reach the SAME HTTP
+    #: endpoint, and must therefore be enforced under this site's ``id`` —
+    #: ``chat.completions.parse`` posts to ``/v1/chat/completions`` just as
+    #: ``create`` does, and would otherwise reach the provider unenforced. Names
+    #: from every client language may be listed; whichever exists on the client
+    #: is patched, and an absent alias is skipped exactly like an absent call
+    #: site. Aliasing adds no new wire id: the cloud contract is unchanged.
+    aliases: tuple[str, ...] = ()
+    #: Keyword arguments whose presence means this call RESUMES a result that
+    #: already exists instead of creating one. Some client methods are
+    #: overloaded: ``responses.stream(response_id=…)`` replays a stored response
+    #: over ``GET /v1/responses/{id}``, where ``responses.stream(model=…,
+    #: input=…)`` creates one over POST. The resuming form carries no prompt and
+    #: no model, so it is let through unenforced — authorizing it would ask the
+    #: cloud to decide about an empty model and sign a token asserting an AI call
+    #: that never happened. It is not a bypass: a call let through carries no ACT
+    #: token, so the net refuses it the moment it turns out to carry a body.
+    resuming_params: tuple[str, ...] = ()
+    forceable_params: frozenset[str] = frozenset()
+    #: Every argument of THIS endpoint that can hand the model a tool, besides
+    #: the provider-wide ``tools_param``. See :class:`ToolField`.
+    tool_fields: tuple[ToolField, ...] = ()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CallSite:
+        return cls(
+            id=data["id"],
+            path=tuple(data["path"]),
+            aliases=tuple(data.get("aliases", ())),
+            resuming_params=tuple(data.get("resuming_params", ())),
+            forceable_params=frozenset(data.get("forceable_params", ())),
+            tool_fields=tuple(
+                ToolField.from_dict(f) for f in data.get("tool_fields", ())
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class ProviderDescriptor:
+    """Declarative description of a provider's injection mechanics.
+
+    ``identity_param`` and ``ubt_param`` are the two exclusive kwargs a caller
+    may use to name the end user (developer-asserted id vs widget-issued User
+    Binding Token). Both are consumed by the SDK, never forwarded to the
+    provider, and excluded from the request hash. ``headers_kwarg`` names the
+    kwarg through which the provider's client accepts per-request HTTP headers
+    (also hash-excluded, since the ACT token travels there).
+    """
+
+    name: str
+    client_module: str
+    call_sites: tuple[CallSite, ...]
+    #: Hosts identifying THIS provider when several descriptors share a
+    #: ``client_module``. OpenAI-compatible providers are all reached through
+    #: the ``openai`` client, so the class name proves nothing — only the base
+    #: URL says who is on the other end. Empty means "the default for this
+    #: module".
+    client_base_url_hosts: frozenset[str] = frozenset()
+    identity_param: str = "user_id"
+    ubt_param: str = "ubt"
+    token_header: str = DEFAULT_CONSENT_HEADER
+    param_target: str = "kwargs"  # "kwargs" | "headers"
+    headers_kwarg: str = "extra_headers"
+    protected_params: frozenset[str] = frozenset()
+    #: Path to the call argument carrying agentic tool definitions, e.g.
+    #: ``("tools",)`` or ``("config", "tools")`` for google-genai. Read — never
+    #: written — to honour a ``tools`` constraint from the cloud. ``None`` means
+    #: the SDK cannot see this provider's tools, and so cannot honour it.
+    tools_param: tuple[str, ...] | None = None
+    #: Headers a caller may never set on an enforced call, as declared: the ones
+    #: that choose which credential, account or project the call goes out on.
+    #: Compare through :meth:`is_reserved_header`, which is case-insensitive and
+    #: always reserves ``token_header`` as well.
+    reserved_headers: tuple[str, ...] = ()
+    #: How several credentials with different privacy postures can be held for
+    #: this provider, or ``None`` when it offers no such thing — in which case
+    #: ``consent.wrap(credentials=…)`` is refused rather than quietly ignored.
+    credential_routing: CredentialRouting | None = None
+    descriptor_version: str = "2"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProviderDescriptor:
+        return cls(
+            name=data["name"],
+            client_module=data["client_module"],
+            call_sites=tuple(CallSite.from_dict(s) for s in data["call_sites"]),
+            client_base_url_hosts=frozenset(data.get("client_base_url_hosts", ())),
+            identity_param=data.get("identity_param", "user_id"),
+            ubt_param=data.get("ubt_param", "ubt"),
+            token_header=data.get("token_header", DEFAULT_CONSENT_HEADER),
+            param_target=data.get("param_target", "kwargs"),
+            headers_kwarg=data.get("headers_kwarg", "extra_headers"),
+            protected_params=frozenset(data.get("protected_params", ())),
+            tools_param=(
+                tuple(data["tools_param"]) if data.get("tools_param") else None
+            ),
+            reserved_headers=tuple(data.get("reserved_headers", ())),
+            credential_routing=(
+                CredentialRouting.from_dict(data["credential_routing"])
+                if data.get("credential_routing")
+                else None
+            ),
+            descriptor_version=data.get("descriptor_version", "2"),
+        )
+
+    def is_reserved_header(self, name: str) -> bool:
+        """Whether a caller-supplied header ``name`` must be refused.
+
+        Case-insensitive, because HTTP header names are, and because the
+        provider libraries merge header maps with case-sensitive dict keys:
+        ``authorization`` next to ``Authorization`` is two headers on the wire,
+        and a list compared by exact spelling would miss the second.
+        """
+        wanted = name.lower()
+        return wanted == self.token_header.lower() or any(
+            wanted == reserved.lower() for reserved in self.reserved_headers
+        )
+
+    def call_site(self, site_id: str) -> CallSite | None:
+        """Look one call site up by its wire id."""
+        return next((s for s in self.call_sites if s.id == site_id), None)
+
+
+def load_descriptors() -> dict[str, ProviderDescriptor]:
+    """Auto-discover and parse every ``*.json`` descriptor in this package."""
+    descriptors: dict[str, ProviderDescriptor] = {}
+    for entry in resources.files(__name__).iterdir():
+        if entry.name.endswith(".json"):
+            data = json.loads(entry.read_text(encoding="utf-8"))
+            descriptor = ProviderDescriptor.from_dict(data)
+            descriptors[descriptor.name] = descriptor
+    return descriptors

idside/providers/anthropic.json

@@ -0,0 +1,108 @@
+{
+  "descriptor_version": "2",
+  "name": "anthropic",
+  "client_module": "anthropic",
+  "call_sites": [
+    {
+      "id": "messages.create",
+      "path": [
+        "messages",
+        "create"
+      ],
+      "aliases": [
+        "parse",
+        "stream"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "mcp_servers"
+          ],
+          "kind": "definitions",
+          "note": "Third-party MCP servers whose tools the model may call. Typed only on the beta endpoint; declared here so a client that accepts it on this one is read the same way."
+        }
+      ],
+      "note": "The only endpoint wrapped, so the per-site list and the provider union are the same today — both empty, see `forceable_params_note`. They are still written separately: the day `/v1/messages/batches` is wrapped, one of them will change and the other must not. Verified 2026-07-26 against `anthropic` 0.111.0: this signature also carries `cache_control`, `container`, `metadata` and `output_config` — none of them forceable, and the first two protected, see `protected_params`."
+    }
+  ],
+  "identity_param": "user_id",
+  "token_header": "X-AI-Consent-Token",
+  "param_target": "kwargs",
+  "protected_params": [
+    "model",
+    "messages",
+    "system",
+    "stream",
+    "cache_control",
+    "container"
+  ],
+  "tools_param": [
+    "tools"
+  ],
+  "reserved_headers": [
+    "X-Api-Key",
+    "Authorization",
+    "api-key"
+  ],
+  "forceable_params": [],
+  "forceable_params_note": "EMPTY since 2026-07-27, and that is a statement rather than an omission. `inference_geo` is a real named parameter of `messages.create`, it lands in the request BODY, and it was verified live — but no option forces it any more: `data_residency` was downgraded to `account` because its two settings (`global`, `us`) do not answer \"inside my region\" for a European user, and we never learn anyone's region. An allowlist entry nothing forces is a door left open for no reason, so it is closed until the option comes back. History worth keeping: this descriptor injected `inference_geo` into HEADERS until 2026-07-26, where Anthropic does not read it — the call succeeded, the residency choice did not apply, and the public matrix showed it as enforced. `param_target` is `kwargs` now. The body schema stays strict (400 `Extra inputs are not permitted`), which is why this allowlist is checked against the real signature by tests/test_forceable_params.py.",
+  "enforcement": {
+    "training.foundation": {
+      "level": "contractual",
+      "protective": false,
+      "note": "No per-request parameter. The Commercial Terms say Anthropic may not train models on Customer Content, but the Service Specific Terms (section E, Development Partner Program) let a customer opt in by enabling the permissive data opt-in setting, after which Anthropic may use the data it submits, including to train models. The developer's organization decides, as with OpenAI's \"unless you explicitly opt in\", and no consent answer changes it; the ACT token is the proof the choice was collected and transmitted. Checked on 2026-10-12 against Anthropic's Commercial Terms and its Service Specific Terms (effective 2026-08-31)."
+    },
+    "training.personalisation": {
+      "level": "unsupported",
+      "note": "No parameter this SDK can send. The pinned client's BETA Messages signature carries a `user_profile_id`, whose semantics are not publicly documented as of 2026-07-26 — noted so this line is not read as 'the API has no such concept', which is no longer safe to claim. The beta endpoint is not wrapped, and the transport guard refuses it."
+    },
+    "training.analytics": {
+      "level": "contractual",
+      "protective": false,
+      "note": "Same terms, and the same exception: the Development Partner Program (Service Specific Terms, section E) lets the customer's organization opt the data it submits in, for Anthropic's products and services. Checked on 2026-10-12."
+    },
+    "memory": {
+      "level": "unsupported",
+      "note": "Not a parameter. Anthropic's `memory` feature reaches the API as a TOOL (`{\"type\": \"memory_...\"}` inside `tools`), so a user who refuses `agentic_tools` already loses it through the tool refusal. What is NOT possible is honouring a refusal of memory alone: the mechanism drops the whole `tools` argument, it cannot remove one entry from it. Declaring this enforced on the strength of the tool refusal would promise a granularity we do not have."
+    },
+    "agentic_tools": {
+      "level": "enforced",
+      "mechanism": "refuse_or_strip_tools",
+      "note": "ENFORCED by the SDK, not by a parameter. Every zero-retention arrangement excludes agentic features while the API itself does not block them: a call that hands the model tools falls outside the retention regime the user was promised, and the SDK is the only component that can see it happening, because it is the only one that sees the outgoing request. When the user has refused, the cloud returns a `tools` constraint and the SDK refuses the call (`ToolUseRefusedError`) or strips the tools, per the constraint. Refusing is the default: an agent stripped of its tools does not fail, it answers wrongly, and the developer has no way to know. Note what is NOT sent to us to make this work: nothing. The constraint follows from the consent state alone — we are never told whether a given call carried tools. Bounded by what the SDK reads: `tools_param` plus the call site's `tool_fields`, which name `mcp_servers` — a SIBLING of `tools` that hands execution to a third party and is excluded from zero retention just as tools are. A refusal read from `tools` alone did not see it, and `extra_body` carried it straight past; per-call options able to rewrite the body are now refused outright. The rule to carry forward: any parameter that delegates execution to a third party is a tool, whatever it is called."
+    },
+    "data_residency": {
+      "level": "account",
+      "routable": true,
+      "note": "Two different questions, and the answers differ — which is why this entry read as self-contradictory until it was spelled out.\n\nPER REQUEST: no. `inference_geo` is real, lands in the body, and was verified live; what does not exist is a VALUE to force. Its two settings are `global` (anywhere) and `us`, the option asks \"keep processing inside my region\", and neither answers that for a European user — who is the one this product is built for. Mapping the question to a value needs the user's region, which we never learn: `location` is `unsupported` at every provider, on purpose. Forcing `us` on a European who asked to stay in their region would be worse than forcing nothing.\n\nBY CREDENTIAL: yes, hence `routable: true`. `workspace_geo` is fixed when a workspace is created and `allowed_inference_geos` is a workspace setting, so a developer holding one workspace per posture lets the SDK send each call to the matching one. That path is the developer's to provision and it needs nobody to know anyone's region.\n\nSo the option stays out of the popup and stays offered to the developer as routable. Re-declaring it `enforced` would need a decision about what \"my region\" means when the provider offers two, and that is a product call rather than a missing line of code. Until 2026-07-27 it was declared `enforced`, the popup asked it, and no rule forced anything: a refusal that reached nothing, recorded in the ledger as though it had been honoured.\n\nVERIFIED by request: `global` (default) or `us`, rejected with 400 on models before Claude 4.6 (confirmed on sonnet-5, refused on haiku-4-5 and sonnet-4-5). The response reports `usage.inference_geo`, so what actually happened is verifiable. Billed x1.1 for `us`. Not available through the OpenAI-compatibility endpoint. This descriptor injected it into HEADERS until 2026-07-26, where Anthropic does not read it — the call succeeded and the residency choice did not apply. `param_target` is `kwargs` now."
+    },
+    "retention.conversation": {
+      "level": "contractual",
+      "protective": false,
+      "note": "No store parameter. Retention is governed by the arrangement; Claude Fable 5 and Mythos 5 are Covered Models with a mandatory 30-day retention that zero-retention cannot override."
+    },
+    "retention.cache": {
+      "level": "contractual",
+      "protective": false,
+      "note": "Prompt caching keeps KV tensors and cryptographic hashes in memory for the TTL. Structured outputs cache the JSON schema for up to 24h — never put personal data in property names, enums, const or pattern. The TTL IS a request parameter here — `cache_control: {type: 'ephemeral', ttl: '5m' | '1h'}` at the root of `messages.create` — but the lever points the other way round from OpenAI's: Anthropic's cache is opt-in, so without `cache_control` there is no cache at all, and FORCING it would create the retention this option exists to refuse. Honouring a refusal therefore means REMOVING an argument the developer passed, which is the tool-refusal mechanism and not `params_forced`; the SDK has no such removal for `cache_control` today, so this stays `contractual` rather than claiming one. `cache_control` is in `protected_params` meanwhile, so the cloud can never write it. Capping an accepted cache at `5m` instead of `1h` would be a genuine forcing, and is the piece worth building first."
+    },
+    "location": {
+      "level": "unsupported",
+      "note": "Not exposed as a request parameter."
+    },
+    "human_review": {
+      "level": "contractual",
+      "protective": false,
+      "note": "No request parameter. Anthropic says no personnel can read retained conversations by default and that human review happens only through a controlled access path — for example when its automated trust and safety systems flag content, which it may then keep up to 2 years whatever the arrangement, zero data retention included. On Covered Models its Service Specific Terms (section F) add that it may retain and perform safety reviews on inputs and outputs, superseding any modified retention commitment such as zero data retention. Nothing rules the review of flagged content out. Checked on 2026-10-12 against Anthropic's Service Specific Terms, its zero-data-retention guide and its privacy-centre articles on retention and Covered Models."
+    },
+    "retention.files": {
+      "level": "unsupported",
+      "note": "No per-request file expiry control on the endpoints this descriptor wraps."
+    }
+  },
+  "enforcement_verified_at": "2026-07-26",
+  "credential_routing": {
+    "unit": "workspace",
+    "note": "API keys belong to a workspace, and `allowed_inference_geos` / retention are workspace settings. Routing means selecting the key, not a header."
+  }
+}