Safety & Grounding

## What a safety setting actually is Gemini runs a classifier over the prompt you send and over each candidate it generates. For every supported harm category it produces an estimated *probability* that the content is unsafe — reported on a coarse scale of `NEGLIGIBLE`, `LOW`, `MEDIUM`, `HIGH`. A `safetySettings` entry is your instruction about where on that scale the API should stop handing content back. It is a **request-level** parameter, not an account setting, so two calls made a second apart can use different strictness. In the google-genai Python SDK the list lives on the generation config: `config=types.GenerateContentConfig(safety_settings=[types.SafetySetting(category=..., threshold=...)])` On the wire it is the `safetySettings` array on the `generateContent` request body, each element `{"category": ..., "threshold": ...}`. ## The categories The configurable harm categories for text generation are harassment, hate speech, sexually explicit content, dangerous content, and civic integrity. They are named with the `HARM_CATEGORY_` prefix (`HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_DANGEROUS_CONTENT`, `HARM_CATEGORY_CIVIC_INTEGRITY`). You set each one independently — a medical-information product typically loosens `DANGEROUS_CONTENT` while leaving harassment and hate speech at their defaults, because loosening everything is both unnecessary and harder to defend in a review. Any category you omit from the array simply keeps the service default for that model. There is no "inherit but stricter" mode; the entry you send fully replaces the default for that one category on that one request. ## The threshold ladder Thresholds are cumulative bands, read as "block content whose probability is at or above this level": - `BLOCK_LOW_AND_ABOVE` — strictest; blocks anything rated LOW, MEDIUM or HIGH. - `BLOCK_MEDIUM_AND_ABOVE` — blocks MEDIUM and HIGH. - `BLOCK_ONLY_HIGH` — blocks only HIGH. - `BLOCK_NONE` — the configurable filter for that category stops blocking. - `OFF` — exposed on newer models to disable that category's filter outright. The common mistake is reading the names as "how bad the content is". They describe the classifier's *confidence*, not severity. Content the model is only mildly suspicious about is exactly what `BLOCK_LOW_AND_ABOVE` catches and what `BLOCK_ONLY_HIGH` lets through, which is why over-strict settings produce so many false refusals on benign domain vocabulary (self-harm helplines, security research, oncology). ## Where the settings apply They govern both directions. If your prompt itself trips a threshold, the whole request is refused before generation: you get no candidates and a `promptFeedback` block reason instead. If the generated candidate trips a threshold, that candidate stops with a safety finish reason. Either way the response carries `safetyRatings` — category plus probability — so you can see which classifier fired rather than guessing. (Vertex AI's variant of the API additionally returns severity fields; the Gemini Developer API's core rating is category + probability, plus a blocked flag.) ## What you cannot turn off Setting every category to the most permissive value does **not** produce an unfiltered model. A separate, non-configurable safety layer always applies to core harms such as child sexual abuse material, and the model's own alignment training still makes it decline requests it considers harmful — that refusal arrives as a normal, successful response whose text is a polite "I can't help with that", not as a filter block. Confusing those two failure modes is the classic interview trap: one is an API-level block you detect from metadata, the other is ordinary generated text. ## Practical guidance Pick thresholds per feature, not per company. A moderation-review console reading user reports needs permissive settings simply to display what it is reviewing; a children's tutoring product wants the strict end. Log the returned ratings alongside your own request id so you can measure the false-refusal rate before you loosen anything, and keep the loosening scoped to the single category that is actually firing. Document the choice: "we set `HARM_CATEGORY_DANGEROUS_CONTENT` to `BLOCK_ONLY_HIGH` because clinical dosage questions were being blocked at MEDIUM" is a defensible sentence in a design review; "we set everything to `BLOCK_NONE`" is not.