# Building an Enterprise-Ready Gemini Client
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
This repository provides a production-ready Python client for the Google Gemini API, serving as a comprehensive example for building robust, enterprise-grade LLM services. It includes key SRE principles like automatic retries, multi-region failover, a circuit breaker pattern, and deep integration with Google Cloud's observability suite (Monitoring and Logging).
## ✨ Features
- ✅ **Automatic Retry with Exponential Backoff** - Resilient API calls with configurable retry logic
- ✅ **Multi-Region Failover** - Automatic region switching on failures for high availability
- ✅ **Circuit Breaker Pattern** - Intelligent region health tracking to avoid wasting time/quota on failing regions
- ✅ **Cloud Monitoring Integration** - Custom metrics for latency, retry count, success/failure rates
- ✅ **Structured Output** - Type-safe responses with Pydantic schema validation
- ✅ **Structured Logging** - Integration with Google Cloud Logging
- ✅ **Async Support** - Full async/await support with AsyncGeminiSREClient
- ✅ **Production Ready** - Comprehensive error handling and observability
- ✅ **File Operations** - Upload and manage files with automatic deduplication
## 📁 Project Structure
```
gemini-sre-client/
├── gemini_sre/ # Main package
│ ├── client.py # Synchronous client
│ ├── async_client.py # Asynchronous client
│ ├── core/ # Core functionality
│ │ ├── circuit_breaker.py
│ │ ├── retry.py
│ │ ├── monitoring.py
│ │ ├── logging.py
│ │ ├── deduplication.py
│ │ └── streaming.py
│ └── proxies/ # SDK proxies
│ ├── models.py
│ ├── chats.py
│ ├── files.py
│ └── async_*.py # Async versions
├── examples/ # 16 working examples
│ ├── basic/ # 4 basic examples
│ ├── advanced/ # 5 advanced examples
│ ├── async/ # 4 async examples
│ └── production/ # 3 production examples
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── docs/ # Documentation
│ ├── api/ # API reference
│ ├── architecture/ # Technical docs
│ └── development/ # Dev docs
├── README.md # This file
├── SETUP.md # Setup instructions
├── setup.py # Package configuration
└── requirements.txt # Dependencies
```
## 🚀 Quick Start
### 1. Installation
```bash
# Clone the repository
git clone <repository-url>
cd gemini-computer-use
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Configure authentication
gcloud auth application-default login
```
### 2. Configuration
Copy the environment template and configure your project:
```bash
# Copy template
cp .env.example .env.local
# Edit .env.local and set your project ID
echo "GOOGLE_CLOUD_PROJECT=your-project-id" > .env.local
```
See [SETUP.md](SETUP.md) for detailed setup instructions.
### 3. Run Your First Example
```bash
# Run basic generation example
.venv/bin/python examples/basic/01_simple_generation.py
# Try streaming
.venv/bin/python examples/basic/02_streaming.py
# Explore all examples
ls examples/
```
## 📖 Usage
### Basic Content Generation
```python
import os
from dotenv import load_dotenv
from gemini_sre import GeminiSREClient
# Load environment variables
load_dotenv('.env.local', override=True)
# Initialize client
client = GeminiSREClient(
project_id=os.getenv("GOOGLE_CLOUD_PROJECT"),
locations=["us-central1", "europe-west1"],
enable_monitoring=False, # Set to True if you have IAM role
enable_logging=False, # Set to True if you have IAM role
)
# Generate content
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explain quantum computing in simple terms",
request_id="example-001",
)
print(response.text)
```
### Streaming Responses
```python
# Stream content for real-time display
for chunk in client.models.generate_content_stream(
model="gemini-2.5-flash",
contents="Write a story about a robot learning to paint",
request_id="stream-001",
):
print(chunk.text, end="", flush=True)
```
### Chat Operations
```python
# Create chat session with context preservation
chat = client.chats.create(
model="gemini-2.5-flash",
request_id="chat-001",
)
# Send messages
response1 = chat.send_message("Hello! My name is Alice.")
response2 = chat.send_message("What's my name?") # Model remembers!
print(response2.text) # "Your name is Alice"
```
### Structured Output with Pydantic
```python
from pydantic import BaseModel, Field
from typing import List
# Define your schema
class Recipe(BaseModel):
name: str = Field(description="Recipe name")
ingredients: List[str] = Field(description="List of ingredients")
steps: List[str] = Field(description="Cooking steps")
cooking_time: int = Field(description="Time in minutes")
# Generate structured output
recipe = client.models.generate_content(
model="gemini-2.5-flash",
contents="Give me a recipe for chocolate chip cookies",
config={
"response_mime_type": "application/json",
"response_schema": Recipe,
},
request_id="recipe-001",
)
# Access typed fields
print(recipe.parsed.name)
print(recipe.parsed.ingredients)
```
### Async Operations
```python
import asyncio
from gemini_sre import AsyncGeminiSREClient
async def main():
# Create async client
client = AsyncGeminiSREClient(
project_id=os.getenv("GOOGLE_CLOUD_PROJECT"),
locations=["us-central1"],
)
# Async generation
response = await client.models.generate_content(
model="gemini-2.5-flash",
contents="Explain async programming",
request_id="async-001",
)
print(response.text)
asyncio.run(main())
```
### Concurrent Requests (4.47x Faster!)
```python
import asyncio
async def make_requests():
client = AsyncGeminiSREClient(
project_id=os.getenv("GOOGLE_CLOUD_PROJECT"),
locations=["us-central1"],
)
# Run 5 requests concurrently
tasks = [
client.models.generate_content(
model="gemini-2.5-flash",
contents=f"What is {topic}?",
request_id=f"req-{i}",
)
for i, topic in enumerate(["Python", "JavaScript", "Go", "Rust", "TypeScript"])
]
# Wait for all to complete
results = await asyncio.gather(*tasks)
return results
# Sequential: ~65s, Concurrent: ~15s (4.47x faster!)
asyncio.run(make_requests())
```
## 📚 Examples
We provide 16 comprehensive examples organized by complexity:
### Basic Examples (4)
- **[01 - Simple Generation](examples/basic/01_simple_generation.py)** - Basic content generation
- **[02 - Streaming](examples/basic/02_streaming.py)** - Real-time streaming responses
- **[03 - Chat Operations](examples/basic/03_chat_operations.py)** - Stateful conversations
- **[04 - Structured Output](examples/basic/04_structured_output.py)** - Pydantic schema validation
### Advanced Examples (5)
- **[01 - Multi-Region](examples/advanced/01_multi_region.py)** - Multi-region failover
- **[02 - Circuit Breaker](examples/advanced/02_circuit_breaker.py)** - Circuit breaker pattern
- **[03 - Custom Retry](examples/advanced/03_custom_retry.py)** - Custom retry strategies
- **[04 - Monitoring](examples/advanced/04_monitoring.py)** - Cloud Monitoring integration
- **[05 - File Operations](examples/advanced/05_file_operations.py)** - File upload/management
### Async Examples (4)
- **[01 - Async Basic](examples/async/01_async_basic.py)** - Basic async operations
- **[02 - Async Streaming](examples/async/02_async_streaming.py)** - Async streaming
- **[03 - Concurrent Requests](examples/async/03_concurrent_requests.py)** - Parallel requests (4.47x speedup!)
- **[04 - Async Chat](examples/async/04_async_chat.py)** - Async chat sessions
### Production Examples (3)
- **[01 - Error Handling](examples/production/01_error_handling.py)** - Comprehensive error patterns
- **[02 - Logging Setup](examples/production/02_logging_setup.py)** - Logging configuration
- **[03 - Best Practices](examples/production/03_best_practices.py)** - Production deployment guide
See [examples/README.md](examples/README.md) for detailed descriptions.
## 🔧 Configuration
### Environment Variables
The client uses standard Google Cloud environment variables for consistency with the genai SDK:
- `GOOGLE_CLOUD_PROJECT` - Your GCP project ID (required)
- `GOOGLE_CLOUD_LOCATION` - Default region (optional)
- `GEMINI_ENABLE_MONITORING` - Enable metrics (optional)
- `GEMINI_ENABLE_LOGGING` - Enable logging (optional)
### Client Configuration
```python
from gemini_sre import GeminiSREClient
from gemini_sre.core import RetryConfig
# Full configuration example
client = GeminiSREClient(
project_id=os.getenv("GOOGLE_CLOUD_PROJECT"),
locations=["us-central1", "europe-west1", "asia-northeast1"],
# Monitoring & Logging
enable_monitoring=True, # Requires roles/monitoring.metricWriter
enable_logging=True, # Requires roles/logging.logWriter
# Retry Configuration
retry_config=RetryConfig(
max_attempts=5,
initial_delay=1.0,
max_delay=16.0,
multiplier=2.0,
),
# Circuit Breaker
enable_circuit_breaker=True,
circuit_breaker_config={
"failure_threshold": 5,
"success_threshold": 2,
"timeout": 60,
},
)
```
## 📊 Monitoring & Observability
### Cloud Monitoring Metrics
The client automatically sends custom metrics to Cloud Monitoring (when enabled):
| Metric | Type | Description |
|--------|------|-------------|
| `gemini_sre/request/success` | COUNTER | Successful requests |
| `gemini_sre/request/error` | COUNTER | Failed requests |
| `gemini_sre/request/latency` | DISTRIBUTION | Request latency (p50, p95, p99) |
| `gemini_sre/request/retry_count` | GAUGE | Retry attempts per request |
| `gemini_sre/circuit_breaker/state` | GAUGE | Circuit breaker state |
All metrics include labels: `location`, `model`, `operation_type`
### Cloud Logging
Structured logs include:
- Request ID for correlation
- Latency and retry counts
- Region information
- Error details
- Success/failure status
View logs in [Cloud Console](https://console.cloud.google.com/logs).
## 🔐 IAM Permissions
**Minimum Required:**
- `roles/aiplatform.user` - Vertex AI API access
**Optional (for full features):**
- `roles/monitoring.metricWriter` - Cloud Monitoring metrics
- `roles/logging.logWriter` - Cloud Logging integration
Set up IAM roles:
```bash
# Grant minimum role
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="user:your-email@example.com" \
--role="roles/aiplatform.user"
```
## 📖 Documentation
- **[Setup Guide](SETUP.md)** - Detailed installation and configuration
- **[API Reference](docs/api/README.md)** - Complete API documentation
- **[Architecture Docs](docs/architecture/)** - Technical design and decisions
- **[Development Guide](docs/development/)** - For contributors
- **[Examples](examples/)** - 16 working code examples
## 🧪 Testing
```bash
# Run unit tests
pytest tests/unit/ -v
# Run integration tests (requires GCP credentials)
pytest tests/integration/ -v
# Run specific test
pytest tests/unit/test_circuit_breaker.py -v
```
## 🏗️ Multi-Region Failover
The client automatically switches regions on failures:
1. **Primary Region** - Tries configured primary (e.g., `us-central1`)
2. **Failover** - Switches to next region on error
3. **Circuit Breaker** - Opens circuit for failing regions (skips them)
4. **Recovery** - Tests region health after timeout
5. **Auto-Close** - Closes circuit when region recovers
**Circuit Breaker States:**
- **CLOSED** (✅) - Normal operation, region healthy
- **OPEN** (🔴) - Region failing, automatically skipped
- **HALF_OPEN** (🟡) - Testing if region recovered
## 🔍 Troubleshooting
### Common Issues
**Permission Denied:**
```bash
# Verify authentication
gcloud auth application-default login
# Check project
gcloud config get-value project
# Verify IAM roles
gcloud projects get-iam-policy YOUR_PROJECT_ID
```
**Module Not Found:**
```bash
# Install in development mode
pip install -e .
```
**Import Errors:**
```python
# Correct import
from gemini_sre import GeminiSREClient # ✅ Correct
# Incorrect import
from gemini_client import GeminiClient # ❌ Old name
```
See [SETUP.md](SETUP.md) for more troubleshooting tips.
## 📦 Dependencies
Core dependencies:
```
google-genai>=1.42.0 # Gemini API SDK
google-cloud-monitoring>=2.27.0 # Custom metrics
google-cloud-logging>=3.12.0 # Structured logging
pydantic>=2.12.0,<3.0.0 # Schema validation
python-dotenv>=1.0.0 # Environment management
```
See [requirements.txt](requirements.txt) for full list.
## 🔗 Useful Links
### Google Gemini
- [Official Docs](https://ai.google.dev/gemini-api/docs)
- [Python SDK](https://github.com/google/generative-ai-python)
- [API Reference](https://ai.google.dev/api/python)
### Pydantic
- [Official Docs](https://docs.pydantic.dev/latest/)
- [BaseModel](https://docs.pydantic.dev/latest/concepts/models/)
- [Field Types](https://docs.pydantic.dev/latest/concepts/fields/)
### Google Cloud
- [Monitoring Docs](https://cloud.google.com/monitoring/docs)
- [Logging Docs](https://cloud.google.com/logging/docs)
- [IAM Docs](https://cloud.google.com/iam/docs)
## 🤝 Contributing
Contributions are welcome! Please see our development documentation:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request
See [docs/development/](docs/development/) for contributor guidelines.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
**TL;DR**: You can freely use, modify, and distribute this code in commercial or non-commercial projects with no restrictions. The author provides no warranty and accepts no liability.
For more information about the license, including what you can and cannot do, see [LICENSE_GUIDE.md](LICENSE_GUIDE.md).
---
**Ready to get started?** Check out [SETUP.md](SETUP.md) for detailed setup instructions, or dive into [examples/](examples/) to see working code!
Raw data
{
"_id": null,
"home_page": null,
"name": "gemini-sre",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "gemini, google, ai, llm, sre, reliability, monitoring, retry, circuit-breaker",
"author": "Giorgio C",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e5/9e/6618c64f969cdd1a66f0f38a9266dd65caed42a7763ed71db2494242c437/gemini_sre-0.0.1.tar.gz",
"platform": null,
"description": "# Building an Enterprise-Ready Gemini Client\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nThis repository provides a production-ready Python client for the Google Gemini API, serving as a comprehensive example for building robust, enterprise-grade LLM services. It includes key SRE principles like automatic retries, multi-region failover, a circuit breaker pattern, and deep integration with Google Cloud's observability suite (Monitoring and Logging).\n\n## \u2728 Features\n\n- \u2705 **Automatic Retry with Exponential Backoff** - Resilient API calls with configurable retry logic\n- \u2705 **Multi-Region Failover** - Automatic region switching on failures for high availability\n- \u2705 **Circuit Breaker Pattern** - Intelligent region health tracking to avoid wasting time/quota on failing regions\n- \u2705 **Cloud Monitoring Integration** - Custom metrics for latency, retry count, success/failure rates\n- \u2705 **Structured Output** - Type-safe responses with Pydantic schema validation\n- \u2705 **Structured Logging** - Integration with Google Cloud Logging\n- \u2705 **Async Support** - Full async/await support with AsyncGeminiSREClient\n- \u2705 **Production Ready** - Comprehensive error handling and observability\n- \u2705 **File Operations** - Upload and manage files with automatic deduplication\n\n## \ud83d\udcc1 Project Structure\n\n```\ngemini-sre-client/\n\u251c\u2500\u2500 gemini_sre/ # Main package\n\u2502 \u251c\u2500\u2500 client.py # Synchronous client\n\u2502 \u251c\u2500\u2500 async_client.py # Asynchronous client\n\u2502 \u251c\u2500\u2500 core/ # Core functionality\n\u2502 \u2502 \u251c\u2500\u2500 circuit_breaker.py\n\u2502 \u2502 \u251c\u2500\u2500 retry.py\n\u2502 \u2502 \u251c\u2500\u2500 monitoring.py\n\u2502 \u2502 \u251c\u2500\u2500 logging.py\n\u2502 \u2502 \u251c\u2500\u2500 deduplication.py\n\u2502 \u2502 \u2514\u2500\u2500 streaming.py\n\u2502 \u2514\u2500\u2500 proxies/ # SDK proxies\n\u2502 \u251c\u2500\u2500 models.py\n\u2502 \u251c\u2500\u2500 chats.py\n\u2502 \u251c\u2500\u2500 files.py\n\u2502 \u2514\u2500\u2500 async_*.py # Async versions\n\u251c\u2500\u2500 examples/ # 16 working examples\n\u2502 \u251c\u2500\u2500 basic/ # 4 basic examples\n\u2502 \u251c\u2500\u2500 advanced/ # 5 advanced examples\n\u2502 \u251c\u2500\u2500 async/ # 4 async examples\n\u2502 \u2514\u2500\u2500 production/ # 3 production examples\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 unit/ # Unit tests\n\u2502 \u2514\u2500\u2500 integration/ # Integration tests\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 api/ # API reference\n\u2502 \u251c\u2500\u2500 architecture/ # Technical docs\n\u2502 \u2514\u2500\u2500 development/ # Dev docs\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 SETUP.md # Setup instructions\n\u251c\u2500\u2500 setup.py # Package configuration\n\u2514\u2500\u2500 requirements.txt # Dependencies\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Installation\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd gemini-computer-use\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate # macOS/Linux\n# .venv\\Scripts\\activate # Windows\n\n# Install dependencies\npip install -r requirements.txt\n\n# Configure authentication\ngcloud auth application-default login\n```\n\n### 2. Configuration\n\nCopy the environment template and configure your project:\n\n```bash\n# Copy template\ncp .env.example .env.local\n\n# Edit .env.local and set your project ID\necho \"GOOGLE_CLOUD_PROJECT=your-project-id\" > .env.local\n```\n\nSee [SETUP.md](SETUP.md) for detailed setup instructions.\n\n### 3. Run Your First Example\n\n```bash\n# Run basic generation example\n.venv/bin/python examples/basic/01_simple_generation.py\n\n# Try streaming\n.venv/bin/python examples/basic/02_streaming.py\n\n# Explore all examples\nls examples/\n```\n\n## \ud83d\udcd6 Usage\n\n### Basic Content Generation\n\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom gemini_sre import GeminiSREClient\n\n# Load environment variables\nload_dotenv('.env.local', override=True)\n\n# Initialize client\nclient = GeminiSREClient(\n project_id=os.getenv(\"GOOGLE_CLOUD_PROJECT\"),\n locations=[\"us-central1\", \"europe-west1\"],\n enable_monitoring=False, # Set to True if you have IAM role\n enable_logging=False, # Set to True if you have IAM role\n)\n\n# Generate content\nresponse = client.models.generate_content(\n model=\"gemini-2.5-flash\",\n contents=\"Explain quantum computing in simple terms\",\n request_id=\"example-001\",\n)\n\nprint(response.text)\n```\n\n### Streaming Responses\n\n```python\n# Stream content for real-time display\nfor chunk in client.models.generate_content_stream(\n model=\"gemini-2.5-flash\",\n contents=\"Write a story about a robot learning to paint\",\n request_id=\"stream-001\",\n):\n print(chunk.text, end=\"\", flush=True)\n```\n\n### Chat Operations\n\n```python\n# Create chat session with context preservation\nchat = client.chats.create(\n model=\"gemini-2.5-flash\",\n request_id=\"chat-001\",\n)\n\n# Send messages\nresponse1 = chat.send_message(\"Hello! My name is Alice.\")\nresponse2 = chat.send_message(\"What's my name?\") # Model remembers!\nprint(response2.text) # \"Your name is Alice\"\n```\n\n### Structured Output with Pydantic\n\n```python\nfrom pydantic import BaseModel, Field\nfrom typing import List\n\n# Define your schema\nclass Recipe(BaseModel):\n name: str = Field(description=\"Recipe name\")\n ingredients: List[str] = Field(description=\"List of ingredients\")\n steps: List[str] = Field(description=\"Cooking steps\")\n cooking_time: int = Field(description=\"Time in minutes\")\n\n# Generate structured output\nrecipe = client.models.generate_content(\n model=\"gemini-2.5-flash\",\n contents=\"Give me a recipe for chocolate chip cookies\",\n config={\n \"response_mime_type\": \"application/json\",\n \"response_schema\": Recipe,\n },\n request_id=\"recipe-001\",\n)\n\n# Access typed fields\nprint(recipe.parsed.name)\nprint(recipe.parsed.ingredients)\n```\n\n### Async Operations\n\n```python\nimport asyncio\nfrom gemini_sre import AsyncGeminiSREClient\n\nasync def main():\n # Create async client\n client = AsyncGeminiSREClient(\n project_id=os.getenv(\"GOOGLE_CLOUD_PROJECT\"),\n locations=[\"us-central1\"],\n )\n\n # Async generation\n response = await client.models.generate_content(\n model=\"gemini-2.5-flash\",\n contents=\"Explain async programming\",\n request_id=\"async-001\",\n )\n\n print(response.text)\n\nasyncio.run(main())\n```\n\n### Concurrent Requests (4.47x Faster!)\n\n```python\nimport asyncio\n\nasync def make_requests():\n client = AsyncGeminiSREClient(\n project_id=os.getenv(\"GOOGLE_CLOUD_PROJECT\"),\n locations=[\"us-central1\"],\n )\n\n # Run 5 requests concurrently\n tasks = [\n client.models.generate_content(\n model=\"gemini-2.5-flash\",\n contents=f\"What is {topic}?\",\n request_id=f\"req-{i}\",\n )\n for i, topic in enumerate([\"Python\", \"JavaScript\", \"Go\", \"Rust\", \"TypeScript\"])\n ]\n\n # Wait for all to complete\n results = await asyncio.gather(*tasks)\n return results\n\n# Sequential: ~65s, Concurrent: ~15s (4.47x faster!)\nasyncio.run(make_requests())\n```\n\n## \ud83d\udcda Examples\n\nWe provide 16 comprehensive examples organized by complexity:\n\n### Basic Examples (4)\n- **[01 - Simple Generation](examples/basic/01_simple_generation.py)** - Basic content generation\n- **[02 - Streaming](examples/basic/02_streaming.py)** - Real-time streaming responses\n- **[03 - Chat Operations](examples/basic/03_chat_operations.py)** - Stateful conversations\n- **[04 - Structured Output](examples/basic/04_structured_output.py)** - Pydantic schema validation\n\n### Advanced Examples (5)\n- **[01 - Multi-Region](examples/advanced/01_multi_region.py)** - Multi-region failover\n- **[02 - Circuit Breaker](examples/advanced/02_circuit_breaker.py)** - Circuit breaker pattern\n- **[03 - Custom Retry](examples/advanced/03_custom_retry.py)** - Custom retry strategies\n- **[04 - Monitoring](examples/advanced/04_monitoring.py)** - Cloud Monitoring integration\n- **[05 - File Operations](examples/advanced/05_file_operations.py)** - File upload/management\n\n### Async Examples (4)\n- **[01 - Async Basic](examples/async/01_async_basic.py)** - Basic async operations\n- **[02 - Async Streaming](examples/async/02_async_streaming.py)** - Async streaming\n- **[03 - Concurrent Requests](examples/async/03_concurrent_requests.py)** - Parallel requests (4.47x speedup!)\n- **[04 - Async Chat](examples/async/04_async_chat.py)** - Async chat sessions\n\n### Production Examples (3)\n- **[01 - Error Handling](examples/production/01_error_handling.py)** - Comprehensive error patterns\n- **[02 - Logging Setup](examples/production/02_logging_setup.py)** - Logging configuration\n- **[03 - Best Practices](examples/production/03_best_practices.py)** - Production deployment guide\n\nSee [examples/README.md](examples/README.md) for detailed descriptions.\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n\nThe client uses standard Google Cloud environment variables for consistency with the genai SDK:\n\n- `GOOGLE_CLOUD_PROJECT` - Your GCP project ID (required)\n- `GOOGLE_CLOUD_LOCATION` - Default region (optional)\n- `GEMINI_ENABLE_MONITORING` - Enable metrics (optional)\n- `GEMINI_ENABLE_LOGGING` - Enable logging (optional)\n\n### Client Configuration\n\n```python\nfrom gemini_sre import GeminiSREClient\nfrom gemini_sre.core import RetryConfig\n\n# Full configuration example\nclient = GeminiSREClient(\n project_id=os.getenv(\"GOOGLE_CLOUD_PROJECT\"),\n locations=[\"us-central1\", \"europe-west1\", \"asia-northeast1\"],\n\n # Monitoring & Logging\n enable_monitoring=True, # Requires roles/monitoring.metricWriter\n enable_logging=True, # Requires roles/logging.logWriter\n\n # Retry Configuration\n retry_config=RetryConfig(\n max_attempts=5,\n initial_delay=1.0,\n max_delay=16.0,\n multiplier=2.0,\n ),\n\n # Circuit Breaker\n enable_circuit_breaker=True,\n circuit_breaker_config={\n \"failure_threshold\": 5,\n \"success_threshold\": 2,\n \"timeout\": 60,\n },\n)\n```\n\n## \ud83d\udcca Monitoring & Observability\n\n### Cloud Monitoring Metrics\n\nThe client automatically sends custom metrics to Cloud Monitoring (when enabled):\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `gemini_sre/request/success` | COUNTER | Successful requests |\n| `gemini_sre/request/error` | COUNTER | Failed requests |\n| `gemini_sre/request/latency` | DISTRIBUTION | Request latency (p50, p95, p99) |\n| `gemini_sre/request/retry_count` | GAUGE | Retry attempts per request |\n| `gemini_sre/circuit_breaker/state` | GAUGE | Circuit breaker state |\n\nAll metrics include labels: `location`, `model`, `operation_type`\n\n### Cloud Logging\n\nStructured logs include:\n- Request ID for correlation\n- Latency and retry counts\n- Region information\n- Error details\n- Success/failure status\n\nView logs in [Cloud Console](https://console.cloud.google.com/logs).\n\n## \ud83d\udd10 IAM Permissions\n\n**Minimum Required:**\n- `roles/aiplatform.user` - Vertex AI API access\n\n**Optional (for full features):**\n- `roles/monitoring.metricWriter` - Cloud Monitoring metrics\n- `roles/logging.logWriter` - Cloud Logging integration\n\nSet up IAM roles:\n```bash\n# Grant minimum role\ngcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\\n --member=\"user:your-email@example.com\" \\\n --role=\"roles/aiplatform.user\"\n```\n\n## \ud83d\udcd6 Documentation\n\n- **[Setup Guide](SETUP.md)** - Detailed installation and configuration\n- **[API Reference](docs/api/README.md)** - Complete API documentation\n- **[Architecture Docs](docs/architecture/)** - Technical design and decisions\n- **[Development Guide](docs/development/)** - For contributors\n- **[Examples](examples/)** - 16 working code examples\n\n## \ud83e\uddea Testing\n\n```bash\n# Run unit tests\npytest tests/unit/ -v\n\n# Run integration tests (requires GCP credentials)\npytest tests/integration/ -v\n\n# Run specific test\npytest tests/unit/test_circuit_breaker.py -v\n```\n\n## \ud83c\udfd7\ufe0f Multi-Region Failover\n\nThe client automatically switches regions on failures:\n\n1. **Primary Region** - Tries configured primary (e.g., `us-central1`)\n2. **Failover** - Switches to next region on error\n3. **Circuit Breaker** - Opens circuit for failing regions (skips them)\n4. **Recovery** - Tests region health after timeout\n5. **Auto-Close** - Closes circuit when region recovers\n\n**Circuit Breaker States:**\n- **CLOSED** (\u2705) - Normal operation, region healthy\n- **OPEN** (\ud83d\udd34) - Region failing, automatically skipped\n- **HALF_OPEN** (\ud83d\udfe1) - Testing if region recovered\n\n## \ud83d\udd0d Troubleshooting\n\n### Common Issues\n\n**Permission Denied:**\n```bash\n# Verify authentication\ngcloud auth application-default login\n\n# Check project\ngcloud config get-value project\n\n# Verify IAM roles\ngcloud projects get-iam-policy YOUR_PROJECT_ID\n```\n\n**Module Not Found:**\n```bash\n# Install in development mode\npip install -e .\n```\n\n**Import Errors:**\n```python\n# Correct import\nfrom gemini_sre import GeminiSREClient # \u2705 Correct\n\n# Incorrect import\nfrom gemini_client import GeminiClient # \u274c Old name\n```\n\nSee [SETUP.md](SETUP.md) for more troubleshooting tips.\n\n## \ud83d\udce6 Dependencies\n\nCore dependencies:\n```\ngoogle-genai>=1.42.0 # Gemini API SDK\ngoogle-cloud-monitoring>=2.27.0 # Custom metrics\ngoogle-cloud-logging>=3.12.0 # Structured logging\npydantic>=2.12.0,<3.0.0 # Schema validation\npython-dotenv>=1.0.0 # Environment management\n```\n\nSee [requirements.txt](requirements.txt) for full list.\n\n## \ud83d\udd17 Useful Links\n\n### Google Gemini\n- [Official Docs](https://ai.google.dev/gemini-api/docs)\n- [Python SDK](https://github.com/google/generative-ai-python)\n- [API Reference](https://ai.google.dev/api/python)\n\n### Pydantic\n- [Official Docs](https://docs.pydantic.dev/latest/)\n- [BaseModel](https://docs.pydantic.dev/latest/concepts/models/)\n- [Field Types](https://docs.pydantic.dev/latest/concepts/fields/)\n\n### Google Cloud\n- [Monitoring Docs](https://cloud.google.com/monitoring/docs)\n- [Logging Docs](https://cloud.google.com/logging/docs)\n- [IAM Docs](https://cloud.google.com/iam/docs)\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our development documentation:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new features\n4. Ensure all tests pass\n5. Submit a pull request\n\nSee [docs/development/](docs/development/) for contributor guidelines.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n**TL;DR**: You can freely use, modify, and distribute this code in commercial or non-commercial projects with no restrictions. The author provides no warranty and accepts no liability.\n\nFor more information about the license, including what you can and cannot do, see [LICENSE_GUIDE.md](LICENSE_GUIDE.md).\n\n---\n\n**Ready to get started?** Check out [SETUP.md](SETUP.md) for detailed setup instructions, or dive into [examples/](examples/) to see working code!\n",
"bugtrack_url": null,
"license": null,
"summary": "Example of Production-ready Google Gemini API wrapper with SRE features",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://github.com/miticojo/gemini-sre-client/blob/main/README.md",
"Homepage": "https://github.com/miticojo/gemini-sre-client",
"Issues": "https://github.com/miticojo/gemini-sre-client/issues",
"Repository": "https://github.com/miticojo/gemini-sre-client"
},
"split_keywords": [
"gemini",
" google",
" ai",
" llm",
" sre",
" reliability",
" monitoring",
" retry",
" circuit-breaker"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f84e76a2db372a49ad7b1e0a73fcb4c2ac78a21cdecdb446da1351f8181e1188",
"md5": "ea598198b835e3a6fc8ba2174681d139",
"sha256": "71207d2f82082bb8dcdbc3b55153bc91d1fb64f96c20864e0278919514efa524"
},
"downloads": -1,
"filename": "gemini_sre-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea598198b835e3a6fc8ba2174681d139",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 37035,
"upload_time": "2025-10-12T13:17:00",
"upload_time_iso_8601": "2025-10-12T13:17:00.495113Z",
"url": "https://files.pythonhosted.org/packages/f8/4e/76a2db372a49ad7b1e0a73fcb4c2ac78a21cdecdb446da1351f8181e1188/gemini_sre-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e59e6618c64f969cdd1a66f0f38a9266dd65caed42a7763ed71db2494242c437",
"md5": "ea3e5cc2f2d8d2ca9d2f1ea5db4f2934",
"sha256": "bbe48d80dd52260d69783e6256d6b40709ad456e2ed9ea19aa82af3bd1e308c0"
},
"downloads": -1,
"filename": "gemini_sre-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "ea3e5cc2f2d8d2ca9d2f1ea5db4f2934",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30536,
"upload_time": "2025-10-12T13:17:01",
"upload_time_iso_8601": "2025-10-12T13:17:01.756546Z",
"url": "https://files.pythonhosted.org/packages/e5/9e/6618c64f969cdd1a66f0f38a9266dd65caed42a7763ed71db2494242c437/gemini_sre-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 13:17:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miticojo",
"github_project": "gemini-sre-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "google-genai",
"specs": [
[
">=",
"1.42.0"
]
]
},
{
"name": "google-adk",
"specs": [
[
">=",
"1.16.0"
]
]
},
{
"name": "google-cloud-monitoring",
"specs": [
[
">=",
"2.27.0"
]
]
},
{
"name": "google-cloud-monitoring-dashboards",
"specs": [
[
">=",
"2.18.0"
]
]
},
{
"name": "google-cloud-logging",
"specs": [
[
">=",
"3.12.0"
]
]
},
{
"name": "google-cloud-aiplatform",
"specs": [
[
">=",
"1.120.0"
]
]
},
{
"name": "google-api-core",
"specs": [
[
">=",
"2.26.0"
]
]
},
{
"name": "google-api-python-client",
"specs": [
[
">=",
"2.184.0"
]
]
},
{
"name": "googleapis-common-protos",
"specs": [
[
">=",
"1.70.0"
]
]
},
{
"name": "google-auth",
"specs": [
[
">=",
"2.41.0"
]
]
},
{
"name": "google-auth-httplib2",
"specs": [
[
">=",
"0.2.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.12.0"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
">=",
"2.11.0"
]
]
}
],
"lcname": "gemini-sre"
}
JSON
