idside 0.1.0.dev0__py3-none-any.whl

idside/providers/deepseek.json

@@ -0,0 +1,108 @@
+{
+  "descriptor_version": "2",
+  "name": "deepseek",
+  "client_module": "openai",
+  "client_base_url_hosts": [
+    "api.deepseek.com"
+  ],
+  "call_sites": [
+    {
+      "id": "chat.completions.create",
+      "path": [
+        "chat",
+        "completions",
+        "create"
+      ],
+      "aliases": [
+        "parse",
+        "stream"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "functions"
+          ],
+          "kind": "definitions",
+          "note": "The legacy form of `tools`: function definitions the model may call. Deprecated, still accepted."
+        },
+        {
+          "path": [
+            "web_search_options"
+          ],
+          "kind": "enabler",
+          "note": "Switches hosted web search on without any `tools` key: an empty object is enough."
+        }
+      ],
+      "note": "DeepSeek is reached through the `openai` client against a different base URL, so this endpoint has the OpenAI client's signature and none of OpenAI's server behaviour. That is exactly the trap: `store` is in the signature and would be accepted by the client, but nothing says the DeepSeek server honours it, and a signature test would 'prove' it does. So this list is empty until a live request says otherwise. There is no Responses API here. `stream` is aliased for the same reason it is on the OpenAI descriptor: it is literally the same client method, and the trap would be the same."
+    }
+  ],
+  "identity_param": "user_id",
+  "ubt_param": "ubt",
+  "token_header": "X-AI-Consent-Token",
+  "param_target": "kwargs",
+  "protected_params": [
+    "model",
+    "messages",
+    "stream"
+  ],
+  "tools_param": [
+    "tools"
+  ],
+  "reserved_headers": [
+    "Authorization",
+    "OpenAI-Organization",
+    "OpenAI-Project"
+  ],
+  "notes": "OpenAI-compatible: the same Python/JS client, pointed at api.deepseek.com. Auto-detection therefore cannot use the client class — an `OpenAI` instance is an `OpenAI` instance — and matches on the base URL host instead. Getting that wrong would send DeepSeek calls to OpenAI's registry rules.",
+  "forceable_params": [],
+  "forceable_params_note": "VERIFIED LIVE 2026-07-26, and the answer is worse than the unknown it replaces: DeepSeek ACCEPTS unknown body fields and SILENTLY DISCARDS them. `store: false` returns 200 and changes nothing, while a KNOWN field of the wrong type (`temperature: \"hot\"`) is refused with 400 — so the server has no unknown-field tier at all. Nothing is declared forceable, and now for a stated reason rather than for want of evidence. The usual signature check is meaningless here: the client is OpenAI's, so it accepts `store` whatever the DeepSeek server does with it, and an offline test would have 'proved' the parameter works. That is the Gemini bug wearing a different hat, and it is why a live suite exists.",
+  "enforcement": {
+    "training.foundation": {
+      "level": "unsupported",
+      "note": "The terms reserve the right to use API inputs and outputs to train and improve the models, and no request parameter or account setting removes it. There is nothing to force and nothing to promise — which is itself the finding a DPO needs."
+    },
+    "training.personalisation": {
+      "level": "unsupported",
+      "note": "Same clause, no lever."
+    },
+    "training.analytics": {
+      "level": "unsupported",
+      "note": "Same clause, no lever."
+    },
+    "memory": {
+      "level": "absent",
+      "note": "Not an API capability. `absent` for that reason: the API has no memory for a refusal to switch off."
+    },
+    "agentic_tools": {
+      "level": "enforced",
+      "mechanism": "refuse_or_strip_tools",
+      "note": "ENFORCED by the SDK, not by a parameter — and the only thing on this list that is. It works here for the same reason it works everywhere: the SDK sees the outgoing request and can refuse it. Note the shape of that: the one control we can offer a DeepSeek user is the one we built ourselves."
+    },
+    "data_residency": {
+      "level": "unsupported",
+      "note": "Data is processed in the People's Republic of China, with no regional endpoint and no parameter. For a GDPR deployment the honest recommendation is not to call api.deepseek.com at all: self-host the open weights, or use a Western host (Bedrock, Together, Fireworks), which is a different provider and gets its own descriptor. This descriptor exists so that an app doing it anyway is at least measured and journalled."
+    },
+    "retention.conversation": {
+      "level": "unsupported",
+      "note": "No `store` equivalent is documented, and the client's `store` parameter is OpenAI's, not DeepSeek's. Settled live on 2026-07-26: sending it returns 200 and does nothing — see `forceable_params_note`. Accepted and discarded is the one result that would let a false `enforced` survive testing, so it is written down here rather than left implied."
+    },
+    "retention.cache": {
+      "level": "unsupported",
+      "note": "Context caching is automatic and billed as a discount; it is not addressable per request."
+    },
+    "location": {
+      "level": "unsupported",
+      "note": "Not exposed as a request parameter."
+    },
+    "human_review": {
+      "level": "unsupported",
+      "note": "No documented commitment either way, which is not the same as a commitment. DeepSeek's Privacy Policy says it monitors interactions to improve its services and that support and safety-monitoring service providers access personal data on its behalf; neither it nor the Open Platform Terms of Service says whether people read API inputs. Refusing here changes nothing. Checked on 2026-10-12 against DeepSeek's Privacy Policy and Open Platform Terms of Service."
+    },
+    "retention.files": {
+      "level": "unsupported",
+      "note": "No per-request file expiry control on the endpoint this descriptor wraps."
+    }
+  },
+  "enforcement_verified_at": "2026-07-26"
+}

idside/providers/gemini.json

@@ -0,0 +1,130 @@
+{
+  "descriptor_version": "2",
+  "name": "gemini",
+  "client_module": "google.genai",
+  "call_sites": [
+    {
+      "id": "models.generate_content",
+      "path": [
+        "models",
+        "generate_content"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "config",
+            "cached_content"
+          ],
+          "js_path": [
+            "config",
+            "cachedContent"
+          ],
+          "kind": "enabler",
+          "note": "A cache created server-side may hold `tools` and `tool_config` of its own."
+        }
+      ]
+    },
+    {
+      "id": "models.generate_content_stream",
+      "path": [
+        "models",
+        "generate_content_stream"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "config",
+            "cached_content"
+          ],
+          "js_path": [
+            "config",
+            "cachedContent"
+          ],
+          "kind": "enabler",
+          "note": "A cache created server-side may hold `tools` and `tool_config` of its own."
+        }
+      ]
+    }
+  ],
+  "identity_param": "user_id",
+  "ubt_param": "ubt",
+  "token_header": "X-AI-Consent-Token",
+  "param_target": "kwargs",
+  "protected_params": [
+    "model",
+    "contents",
+    "config",
+    "http_options"
+  ],
+  "tools_param": [
+    "config",
+    "tools"
+  ],
+  "reserved_headers": [
+    "x-goog-api-key",
+    "Authorization",
+    "x-goog-user-project"
+  ],
+  "notes": "google-genai's generate_content accepts exactly (model, contents, config) and no free-form kwargs, so the generic kwargs/headers engine cannot inject anything at the top level. Per-request headers ARE supported, but only nested as config.http_options.headers (merged over the client-level headers by the google-genai transport). The Python SDK therefore ships a built-in Gemini adapter that (1) carries the ACT token in config.http_options.headers and (2) merges any cloud-forced params into config, normalizing a GenerateContentConfig object to its dict form when needed. The Gemini API exposes no per-request no-training parameter (retention/training controls are account-level), so the cloud is expected to return params_forced: {} — the enforcement value here is the ACT token and the ledger entry.",
+  "forceable_params": [],
+  "forceable_params_note": "Verified 2026-07-25: `google-genai`'s generate_content() accepts only model/contents/config, and the REST API rejects unknown fields (400). Forcing anything here breaks every call.",
+  "enforcement": {
+    "training.foundation": {
+      "level": "account",
+      "note": "No API-level opt-out. Paid Services: prompts, cached content, files and responses are not used to improve Google products. Unpaid Services: they are, with possible human review — except for a developer in the EEA, Switzerland or the UK, who gets the Paid Services data-use terms on unpaid quota too. The lever is the billing tier, which the developer chooses; any app offered to users in the EEA, Switzerland or the UK may use only Paid Services, so for those users there is no unpaid project to route to. Elsewhere, it can still be honoured per user IF the developer provisions one project per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "training.personalisation": {
+      "level": "account",
+      "note": "Same tier dependency. Can still be honoured per user IF the developer provisions one project per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "training.analytics": {
+      "level": "account",
+      "note": "Same tier dependency. Can still be honoured per user IF the developer provisions one project per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "memory": {
+      "level": "absent",
+      "note": "A Gemini app feature, not an API one. `absent` for that reason: the API has no memory for a refusal to switch off."
+    },
+    "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."
+    },
+    "data_residency": {
+      "level": "unsupported",
+      "note": "Not available on the Developer API. Vertex AI offers regional endpoints, VPC-SC and CMEK — a different product this descriptor does not wrap."
+    },
+    "retention.conversation": {
+      "level": "unsupported",
+      "note": "VERIFIED: `generate_content()` accepts only model/contents/config and the REST API rejects unknown fields with HTTP 400, so nothing can be forced on the endpoints wrapped here. That is not the whole picture and the difference matters: `client.interactions` EXISTS in the pinned `google-genai` 2.11.0, its `create` takes a `store` that defaults to TRUE, and it keeps the Interaction object 55 days on a paid tier. A developer migrating to the Interactions API creates 55 days of retention by changing nothing else. So this line means 'the SDK does not reach it yet', not 'Google offers nothing' — the endpoint is refused by the transport guard meanwhile, and adding it as a call site is a backlog card, blocked on the ACT token's route into a client whose adapter nests headers in `config.http_options` while `interactions.create` has no `config` at all. Also: never configure SessionResumptionConfig on the Live API, it retains conversational state for 24h — `client.live` is absent from 2.11.0, so that is a warning for a later client, not a live risk."
+    },
+    "retention.cache": {
+      "level": "account",
+      "note": "Implicit in-memory caching (24h, per project) cannot be disabled per request; on Vertex it is a project-level cacheConfig — that is what makes this account-level. The EXPLICIT cache is a different thing and this line used to obscure it: `caches.create` takes `ttl`, `expire_time` and even `kms_key_name` per call, so a developer who creates caches decides their lifetime. That endpoint is not wrapped, and `cached_content` on a wrapped call points AT such a cache rather than configuring one, so there is nothing to force here. Avoid `cached_content` entirely for a zero footprint. Can still be honoured per user IF the developer provisions one project per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "location": {
+      "level": "unsupported",
+      "note": "Not exposed as a request parameter."
+    },
+    "human_review": {
+      "level": "contractual",
+      "protective": false,
+      "note": "No request parameter, and no project setting rules it out: Google's terms decide it, on either billing tier. Google's abuse-monitoring page, which covers the Gemini API and AI Studio, says prompts, contextual information and output are kept 55 days to detect violations of the Prohibited Use Policy, that authorized Google employees may assess what its safety filters and abuse detection flag, and that a project showing consistently suspicious activity may be flagged for manual review. Its zero-retention page names no Developer API control for that logging and points to Vertex AI for guaranteed zero retention. The Unpaid Services terms add routine review: human reviewers may read, annotate and process API input and output to improve Google's products, once it is disconnected from the Google Account, API key and Cloud project — on unpaid quota, and on any dataset a billed project chooses to share with Google from its Gemini API logs. Unpaid quota gets the Paid Services data-use terms for a developer in the EEA, Switzerland or the UK, and an app offered to people there may use only Paid Services. A billed project that shares no dataset removes routine review — the lever the training options route on — and never the review of flagged content, so no project honours a refusal and there is no posture to route one to. Checked on 2026-10-12 against Google's Gemini API Additional Terms and its abuse-monitoring, zero-retention and data-logging pages."
+    },
+    "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": "project",
+    "note": "Whether prompts train Google's models depends on the billing tier of the project behind the key. Routing means selecting the key."
+  }
+}

idside/providers/mistral.json

@@ -0,0 +1,195 @@
+{
+  "descriptor_version": "2",
+  "name": "mistral",
+  "client_module": "mistralai",
+  "call_sites": [
+    {
+      "id": "chat.complete",
+      "path": [
+        "chat",
+        "complete"
+      ],
+      "forceable_params": []
+    },
+    {
+      "id": "chat.stream",
+      "path": [
+        "chat",
+        "stream"
+      ],
+      "forceable_params": []
+    },
+    {
+      "id": "fim.complete",
+      "path": [
+        "fim",
+        "complete"
+      ],
+      "forceable_params": []
+    },
+    {
+      "id": "fim.stream",
+      "path": [
+        "fim",
+        "stream"
+      ],
+      "forceable_params": []
+    },
+    {
+      "id": "agents.complete",
+      "path": [
+        "agents",
+        "complete"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "agent_id"
+          ],
+          "js_path": [
+            "agentId"
+          ],
+          "kind": "enabler",
+          "note": "A server-side agent carries its own `tools` and `handoffs`, which the SDK cannot see. Required on `agents.*`, so a refusal of tools refuses every agent call."
+        }
+      ]
+    },
+    {
+      "id": "agents.stream",
+      "path": [
+        "agents",
+        "stream"
+      ],
+      "forceable_params": [],
+      "tool_fields": [
+        {
+          "path": [
+            "agent_id"
+          ],
+          "js_path": [
+            "agentId"
+          ],
+          "kind": "enabler",
+          "note": "A server-side agent carries its own `tools` and `handoffs`, which the SDK cannot see. Required on `agents.*`, so a refusal of tools refuses every agent call."
+        }
+      ]
+    },
+    {
+      "id": "beta.conversations.start",
+      "path": [
+        "beta",
+        "conversations",
+        "start"
+      ],
+      "forceable_params": [
+        "store"
+      ],
+      "tool_fields": [
+        {
+          "path": [
+            "agent_id"
+          ],
+          "js_path": [
+            "agentId"
+          ],
+          "kind": "enabler",
+          "note": "A server-side agent carries its own `tools` and `handoffs`, which the SDK cannot see. Required on `agents.*`, so a refusal of tools refuses every agent call."
+        }
+      ],
+      "note": "The stateful endpoint, and the only one of this provider's with a retention lever. `store` was confirmed live on /v1/conversations first, and again offline on 2026-07-26 against `mistralai` 2.6.0, whose `beta.conversations.start` signature carries `store`, `model` AND `http_headers` — so the endpoint needs nothing this descriptor cannot already do. Spelled the same in the JS client, which is why no per-language alias is needed. `start_stream` (`startStream` in JS) reaches the same endpoint and is NOT listed: the two clients spell it differently and a `path` is matched literally, so listing it would enforce one SDK and not the other. Until it is added properly it stays refused by the transport guard, which is the safe half of that asymmetry. `append`, `restart` and the rest are refused likewise — they extend a conversation whose creation was the choice."
+    }
+  ],
+  "identity_param": "user_id",
+  "ubt_param": "ubt",
+  "token_header": "X-AI-Consent-Token",
+  "param_target": "kwargs",
+  "headers_kwarg": "http_headers",
+  "protected_params": [
+    "model",
+    "messages",
+    "prompt",
+    "agent_id",
+    "stream",
+    "http_headers"
+  ],
+  "tools_param": [
+    "tools"
+  ],
+  "reserved_headers": [
+    "Authorization"
+  ],
+  "notes": "The native mistralai client (Speakeasy-generated, v1.5+) accepts per-request headers through the http_headers keyword on every call site listed here, so the generic engine handles it declaratively: forced params go to kwargs, the ACT token travels in http_headers. Mistral's API exposes no per-request no-training parameter (zero-retention/no-training is contractual, at account level), so the cloud is expected to return params_forced: {} — the enforcement value here is the ACT token and the ledger entry. Note chat.parse is not listed: it funnels into chat.complete on the same instance, which is already enforced. Import trap worth recording: `mistralai` 2.6.0 is a namespace package and `from mistralai import Mistral` now raises ImportError — the working path is `from mistralai.client import Mistral`. `client_module: \"mistralai\"` is nonetheless still correct, and was rechecked on 2026-07-26: detection matches the root of the client INSTANCE's module (`mistralai.client.sdk` -> `mistralai`), never an attribute of the top-level package.",
+  "forceable_params": [
+    "store"
+  ],
+  "forceable_params_note": "Verified 2026-07-26 against the pinned `mistralai` client, per call site. The stateless sites (`chat`, `fim`, `agents`) force nothing: the REST API rejects unknown body fields (422), no privacy parameter exists at that level, and the training opt-out is console-only. `beta.conversations.start` is the exception and carries `store`. `prompt_cache_key` is a routing hint and `safe_prompt`/`guardrails` are moderation — neither is a retention control, and neither is declared.",
+  "enforcement": {
+    "training.foundation": {
+      "level": "account",
+      "note": "Console toggle 'Data usage for improving our services'. Scale is opted out by default; Experiment users must switch off 'Anonymous improvement data' themselves. WARNING: enabling Labs models allows training regardless of plan and of every opt-out. Can still be honoured per user IF the developer provisions one organisation per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "training.personalisation": {
+      "level": "account",
+      "note": "Same console setting. Can still be honoured per user IF the developer provisions one organisation per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "training.analytics": {
+      "level": "account",
+      "note": "Same console setting. Can still be honoured per user IF the developer provisions one organisation per posture — the SDK then routes each call to the one matching that user's answer. See `credential_routing`.",
+      "routable": true
+    },
+    "memory": {
+      "level": "absent",
+      "note": "Not an API capability. `absent` for that reason: the API has no memory for a refusal to switch off."
+    },
+    "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."
+    },
+    "data_residency": {
+      "level": "account",
+      "note": "Chosen by ENDPOINT, not by a request parameter. Mistral hosts data in the EU by default, but where inference runs follows the base URL: `api.eu.mistral.ai` (EU and EFTA data centres) and `api.us.mistral.ai` process inference inside their region, at a 10% upcharge, while the global `api.mistral.ai`, which a client uses when it names no region, commits to no inference location. A client names a region with `server_url`, or with `server` set to `eu` or `us` from `mistralai` 2.7.0; before `mistralai` 2.7.0 — including the releases this repository tests against (Python 2.6.0, Node 2.4.1) — `server` set to `eu` still names the global endpoint. A regional endpoint does not make the control plane regional (keys, billing and usage metadata may be handled elsewhere), serves only the models hosted in its region, supports function calling as its only tool and offers no Agents, Batch or Files API; a workload that relies on one of those loses the regional guarantee. Can still be honoured per user IF the developer provisions one client per posture, each built on the endpoint it requires — the SDK then routes each call to the one matching that user's answer. See `credential_routing`. Checked on 2026-10-12 against Mistral's regional-inference documentation and the `mistralai` releases.",
+      "routable": true
+    },
+    "retention.conversation": {
+      "level": "enforced",
+      "params": [
+        {
+          "name": "store",
+          "call_sites": [
+            "beta.conversations.start"
+          ],
+          "when": false,
+          "value": false,
+          "note": "VERIFIED by request: `store: false` IS accepted on /v1/conversations (200, while an unknown field gives 422), and confirmed a second time offline against the pinned client's signature. It applies to that endpoint ALONE: `chat.complete` is stateless and has no such parameter, which is why this is declared per call site and not on the provider."
+        }
+      ],
+      "note": "One parameter, one endpoint. A developer using only `chat.complete` gets nothing from this line, and the per-site allowlist is what says so — the cloud is told which endpoint is about to be called and answers for that one. Conversations the SDK does not wrap (`append`, `restart`, `start_stream`) are refused by the transport guard rather than silently enforced."
+    },
+    "retention.cache": {
+      "level": "unsupported",
+      "note": "`prompt_cache_key` is a routing hint, not a retention control. `safe_prompt` and `guardrails` are moderation, not privacy — do not confuse them."
+    },
+    "location": {
+      "level": "unsupported",
+      "note": "Not exposed as a request parameter."
+    },
+    "human_review": {
+      "level": "contractual",
+      "protective": false,
+      "note": "No request parameter, and no console setting for it: the Admin panel's Privacy settings hold the training toggle (\"Anonymous improvement data\") and, once Mistral has approved it, Zero Data Retention. What Mistral writes does not read like OpenAI's, Anthropic's or Google's. Its Data Processing Addendum describes abuse monitoring on the APIs as automated moderation, which stops once Zero Data Retention is active, and its Privacy Policy keeps API input and output 30 rolling days to monitor abuse unless it is; the only human access its help centre describes is to content a customer reports to support, in an article that names no API; and its Commercial Terms license customer data for \"debugging, assessing, reviewing, and correcting the performance\" of the products without saying by whom. No document says Mistral staff review API traffic, and none rules it out: the terms decide. Zero Data Retention ends abuse-monitoring retention but is no posture to route a refusal on: it is granted at Mistral's discretion, on pay-as-you-go only, it covers stateless endpoints and not the agents and conversations this descriptor also wraps, and nothing written says what it changes for human review. Checked on 2026-10-12 against Mistral's Commercial Terms of Service, Data Processing Addendum, Privacy Policy and help-centre articles on Zero Data Retention, training opt-out and who can view conversations."
+    },
+    "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": "organisation",
+    "note": "The training toggle is an organisation setting in the console. Routing means selecting the key."
+  }
+}