0
# Safety and Configuration
1

2
Content safety controls and configuration options for responsible AI deployment. Provides comprehensive filtering capabilities, error handling, and system configuration for all Google Generative AI components.
3

4
## Capabilities
5

6
### Safety Enums
7

8
#### HarmCategory
9

10
Categories of potentially harmful content that can be filtered by Google's safety systems.
11

12
```python { .api }
13
# From google.ai.generativelanguage_v1beta.HarmCategory
14
HarmCategory.HARM_CATEGORY_HARASSMENT
15
HarmCategory.HARM_CATEGORY_HATE_SPEECH  
16
HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT
17
HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT
18
HarmCategory.HARM_CATEGORY_CIVIC_INTEGRITY
19
```
20

21
**Categories:**
22
- `HARM_CATEGORY_HARASSMENT`: Content that harasses, intimidates, bullies, or abuses
23
- `HARM_CATEGORY_HATE_SPEECH`: Content that promotes hatred against individuals or groups
24
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: Content containing explicit sexual material
25
- `HARM_CATEGORY_DANGEROUS_CONTENT`: Content that could facilitate harm to individuals or groups
26
- `HARM_CATEGORY_CIVIC_INTEGRITY`: Content that could undermine civic processes or institutions
27

28
#### HarmBlockThreshold
29

30
Threshold levels for content filtering, determining when to block potentially harmful content.
31

32
```python { .api }
33
# From google.ai.generativelanguage_v1beta.SafetySetting.HarmBlockThreshold
34
HarmBlockThreshold.BLOCK_NONE
35
HarmBlockThreshold.BLOCK_ONLY_HIGH
36
HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
37
HarmBlockThreshold.BLOCK_LOW_AND_ABOVE
38
```
39

40
**Thresholds:**
41
- `BLOCK_NONE`: Don't block any content based on this category
42
- `BLOCK_ONLY_HIGH`: Block only high-probability harmful content
43
- `BLOCK_MEDIUM_AND_ABOVE`: Block medium and high-probability harmful content (recommended)
44
- `BLOCK_LOW_AND_ABOVE`: Block low, medium, and high-probability harmful content (most restrictive)
45

46
#### Modality
47

48
Generation modality options for multimodal capabilities.
49

50
```python { .api }
51
# From google.ai.generativelanguage_v1beta.GenerationConfig.Modality
52
Modality.TEXT
53
Modality.IMAGE
54
Modality.AUDIO
55
```
56

57
**Modalities:**
58
- `TEXT`: Text-only generation
59
- `IMAGE`: Image generation capabilities
60
- `AUDIO`: Audio generation capabilities
61

62
### Exception Classes
63

64
#### DoesNotExistsException
65

66
Exception raised when trying to access non-existent vector store resources. This is the only exception class exported by the package.
67

68
```python { .api }
69
class DoesNotExistsException(Exception):
70
    def __init__(self, *, corpus_id: str, document_id: Optional[str] = None)
71
```
72

73
**Parameters:**
74
- `corpus_id` (str): The corpus ID that doesn't exist
75
- `document_id` (Optional[str]): The document ID that doesn't exist (if applicable)
76

77
### Type Definitions
78

79
#### SafetySettingDict
80

81
Type definition for safety setting configuration.
82

83
```python { .api }
84
SafetySettingDict = TypedDict('SafetySettingDict', {
85
    'category': HarmCategory,
86
    'threshold': HarmBlockThreshold
87
})
88
```
89

90
## Usage Examples
91

92
### Basic Safety Configuration
93

94
```python
95
from langchain_google_genai import (
96
    ChatGoogleGenerativeAI,
97
    HarmCategory,
98
    HarmBlockThreshold
99
)
100

101
# Configure comprehensive safety settings
102
safety_settings = {
103
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
104
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
105
    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
106
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
107
}
108

109
# Initialize model with safety settings
110
llm = ChatGoogleGenerativeAI(
111
    model="gemini-2.5-pro",
112
    safety_settings=safety_settings
113
)
114

115
try:
116
    response = llm.invoke("Generate helpful and safe content about AI")
117
    print(response.content)
118
except Exception as e:
119
    print(f"Generation error: {e}")
120
```
121

122
### Custom Safety Levels
123

124
```python
125
# Strict safety settings (most restrictive)
126
strict_settings = {
127
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
128
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
129
    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
130
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
131
}
132

133
strict_llm = ChatGoogleGenerativeAI(
134
    model="gemini-2.5-pro",
135
    safety_settings=strict_settings
136
)
137

138
# Permissive settings (less restrictive)
139
permissive_settings = {
140
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
141
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_ONLY_HIGH,
142
    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
143
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
144
}
145

146
permissive_llm = ChatGoogleGenerativeAI(
147
    model="gemini-2.5-pro",
148
    safety_settings=permissive_settings
149
)
150
```
151

152
### Multimodal Configuration
153

154
```python
155
from langchain_google_genai import Modality
156

157
# Configure for multimodal output
158
multimodal_llm = ChatGoogleGenerativeAI(
159
    model="gemini-2.0-flash",
160
    response_modalities=[Modality.TEXT, Modality.IMAGE],
161
    safety_settings={
162
        HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
163
        HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
164
    }
165
)
166

167
response = multimodal_llm.invoke("Create a diagram explaining photosynthesis")
168
print("Response includes:", response.response_metadata.get("modalities", ["text"]))
169
```
170

171
### Error Handling Strategies
172

173
```python
174
from langchain_google_genai import ChatGoogleGenerativeAI
175

176
def safe_generate(prompt: str, max_retries: int = 3):
177
    """Generate content with comprehensive error handling."""
178
    
179
    llm = ChatGoogleGenerativeAI(
180
        model="gemini-2.5-pro",
181
        safety_settings={
182
            HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
183
            HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
184
        }
185
    )
186
    
187
    for attempt in range(max_retries):
188
        try:
189
            response = llm.invoke(prompt)
190
            return {"success": True, "content": response.content, "attempt": attempt + 1}
191
            
192
        except Exception as e:
193
            if "safety" in str(e).lower():
194
                return {
195
                    "success": False, 
196
                    "error": "Content blocked by safety filters",
197
                    "details": str(e)
198
                }
199
            elif "api" in str(e).lower() or "rate" in str(e).lower():
200
                if attempt < max_retries - 1:
201
                    print(f"Attempt {attempt + 1} failed, retrying...")
202
                    continue
203
                else:
204
                    return {
205
                        "success": False,
206
                        "error": "API error after retries",
207
                        "details": str(e)
208
                    }
209
            else:
210
                return {
211
                    "success": False,
212
                    "error": "Generation error",
213
                    "details": str(e)
214
                }
215

216
# Use safe generation
217
result = safe_generate("Explain quantum computing")
218
if result["success"]:
219
    print(f"Generated content: {result['content']}")
220
else:
221
    print(f"Generation failed: {result['error']}")
222
```
223

224
### Vector Store Error Handling
225

226
```python
227
from langchain_google_genai import GoogleVectorStore, DoesNotExistsException
228

229
def safe_vector_operations():
230
    """Demonstrate safe vector store operations."""
231
    
232
    try:
233
        # Try to connect to existing corpus
234
        vector_store = GoogleVectorStore(corpus_id="my-corpus")
235
        print("Connected to existing corpus")
236
        
237
    except DoesNotExistsException as e:
238
        print(f"Corpus doesn't exist: {e}")
239
        
240
        # Create new corpus
241
        vector_store = GoogleVectorStore.create_corpus(
242
            corpus_id="my-corpus",
243
            display_name="My Knowledge Base"
244
        )
245
        print("Created new corpus")
246
    
247
    try:
248
        # Try to add content to specific document
249
        vector_store.add_texts(
250
            ["Sample content"],
251
            document_id="specific-doc"
252
        )
253
        
254
    except DoesNotExistsException as e:
255
        print(f"Document doesn't exist: {e}")
256
        
257
        # Create document first
258
        doc_store = GoogleVectorStore.create_document(
259
            corpus_id="my-corpus",
260
            document_id="specific-doc",
261
            display_name="My Document"
262
        )
263
        doc_store.add_texts(["Sample content"])
264
        print("Created document and added content")
265

266
safe_vector_operations()
267
```
268

269
### Safety Setting Validation
270

271
```python
272
def validate_safety_settings(settings: Dict[HarmCategory, HarmBlockThreshold]) -> bool:
273
    """Validate safety settings configuration."""
274
    
275
    required_categories = {
276
        HarmCategory.HARM_CATEGORY_HARASSMENT,
277
        HarmCategory.HARM_CATEGORY_HATE_SPEECH,
278
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
279
    }
280
    
281
    # Check if all required categories are covered
282
    missing_categories = required_categories - set(settings.keys())
283
    if missing_categories:
284
        print(f"Warning: Missing safety settings for: {missing_categories}")
285
        return False
286
    
287
    # Check for overly permissive settings
288
    permissive_settings = [
289
        (category, threshold) for category, threshold in settings.items()
290
        if threshold == HarmBlockThreshold.BLOCK_NONE
291
    ]
292
    
293
    if permissive_settings:
294
        print(f"Warning: Permissive settings detected: {permissive_settings}")
295
        
296
    return True
297

298
# Validate settings before use
299
safety_config = {
300
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
301
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
302
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
303
}
304

305
if validate_safety_settings(safety_config):
306
    llm = ChatGoogleGenerativeAI(
307
        model="gemini-2.5-pro",
308
        safety_settings=safety_config
309
    )
310
```
311

312
### Environment-Based Configuration
313

314
```python
315
import os
316

317
def get_safety_config():
318
    """Get safety configuration based on environment."""
319
    
320
    env = os.getenv("DEPLOYMENT_ENV", "production")
321
    
322
    if env == "development":
323
        # More permissive for development
324
        return {
325
            HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
326
            HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_ONLY_HIGH,
327
            HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
328
        }
329
    else:
330
        # Strict for production
331
        return {
332
            HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
333
            HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
334
            HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
335
            HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
336
        }
337

338
# Use environment-based configuration
339
llm = ChatGoogleGenerativeAI(
340
    model="gemini-2.5-pro",
341
    safety_settings=get_safety_config()
342
)
343
```
344

345
### Safety Monitoring
346

347
```python
348
def monitor_safety_blocks(llm, prompts: List[str]):
349
    """Monitor safety blocking rates for a set of prompts."""
350
    
351
    total_prompts = len(prompts)
352
    blocked_prompts = 0
353
    successful_prompts = 0
354
    
355
    results = []
356
    
357
    for prompt in prompts:
358
        try:
359
            response = llm.invoke(prompt)
360
            successful_prompts += 1
361
            results.append({
362
                "prompt": prompt[:50] + "...",
363
                "status": "success",
364
                "response_length": len(response.content)
365
            })
366
            
367
        except Exception as e:
368
            if "safety" in str(e).lower():
369
                blocked_prompts += 1
370
                results.append({
371
                    "prompt": prompt[:50] + "...",
372
                    "status": "blocked",
373
                    "reason": "safety filter"
374
                })
375
            else:
376
                results.append({
377
                    "prompt": prompt[:50] + "...",
378
                    "status": "error",
379
                    "reason": str(e)
380
                })
381
    
382
    # Print statistics
383
    print(f"Safety Monitoring Results:")
384
    print(f"Total prompts: {total_prompts}")
385
    print(f"Successful: {successful_prompts} ({successful_prompts/total_prompts:.1%})")
386
    print(f"Blocked: {blocked_prompts} ({blocked_prompts/total_prompts:.1%})")
387
    
388
    return results
389

390
# Example monitoring
391
test_prompts = [
392
    "Explain machine learning",
393
    "Write a story about robots",
394
    "Describe cooking techniques",
395
]
396

397
llm = ChatGoogleGenerativeAI(
398
    model="gemini-2.5-pro",
399
    safety_settings={
400
        HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
401
    }
402
)
403

404
monitoring_results = monitor_safety_blocks(llm, test_prompts)
405
```
406

407
## Best Practices
408

409
1. **Use recommended settings**: Start with `BLOCK_MEDIUM_AND_ABOVE` for most categories
410
2. **Cover all categories**: Configure safety settings for all relevant harm categories
411
3. **Environment-specific config**: Use stricter settings in production environments
412
4. **Handle exceptions gracefully**: Implement proper error handling for safety blocks
413
5. **Monitor blocking rates**: Track how often content is blocked to adjust settings
414
6. **Validate configurations**: Check safety settings before deployment
415
7. **Document safety decisions**: Maintain records of safety configuration choices
416
8. **Regular review**: Periodically review and update safety settings as needed
417
9. **Test with edge cases**: Validate safety behavior with potentially problematic content
418
10. **User feedback**: Provide clear messaging when content is blocked by safety filters