hanzoai/python-sdk
2
0
Fork 0
mirror of https://github.com/hanzoai/python-sdk.git synced 2026-10-23 20:23:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update gitignore

Browse Source
This commit is contained in:
zeekay
2025-10-28 10:55:03 -07:00
parent 08caf37d59
commit 27fd1769f6
3 changed files with 7 additions and 1567 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+7 -1
View File
@@ -15,6 +15,12 @@ dist
codegen.log
Brewfile.lock.json
AGENTS.md
LLM.md
AGENTS.md
CLAUDE.md
GEMINI.md
GROK.md
QWEN.md
CLAUDE.md
-865
View File
@@ -1,865 +0,0 @@
# Claude-Specific Workflow Patterns
## Overview
This document provides comprehensive patterns for working with Anthropic's Claude models through hanzo-mcp. It covers the Claude model family, Constitutional AI principles, and optimizations specific to Claude's strengths.
## Claude Model Family
### Model Tiers
```python
CLAUDE_MODELS = {
# Opus - Most capable, slowest
"claude-3-opus-20240229": {
"context_window": 200_000,
"strengths": ["deep reasoning", "complex analysis", "nuanced understanding"],
"cost_tier": "premium",
"best_for": ["architecture design", "code review", "security analysis"],
"speed": "slow",
"intelligence": "highest"
},
# Sonnet - Balanced performance
"claude-3-5-sonnet-20241022": {
"context_window": 200_000,
"strengths": ["code generation", "balanced speed/quality", "tool use"],
"cost_tier": "balanced",
"best_for": ["implementation", "refactoring", "general development"],
"speed": "medium",
"intelligence": "high"
},
"claude-3-sonnet-20240229": {
"context_window": 200_000,
"strengths": ["reasoning", "code understanding"],
"cost_tier": "balanced",
"best_for": ["analysis", "documentation"],
"speed": "medium",
"intelligence": "high"
},
# Haiku - Fast and efficient
"claude-3-haiku-20240307": {
"context_window": 200_000,
"strengths": ["speed", "efficiency", "simple tasks"],
"cost_tier": "budget",
"best_for": ["formatting", "simple edits", "quick answers"],
"speed": "fast",
"intelligence": "good"
},
# Legacy
"claude-2.1": {
"context_window": 200_000,
"strengths": ["long context", "stability"],
"cost_tier": "legacy",
"best_for": ["backward compatibility"],
"speed": "medium",
"intelligence": "good"
}
}
```
### Model Selection Strategy
```python
def select_claude_model(task_type: str, quality_requirement: str = "balanced"):
"""Select optimal Claude model for task."""
task_model_map = {
# High complexity tasks
"architecture": "claude-3-opus-20240229",
"security_audit": "claude-3-opus-20240229",
"complex_debugging": "claude-3-opus-20240229",
# Code generation tasks
"implementation": "claude-3-5-sonnet-20241022",
"refactoring": "claude-3-5-sonnet-20241022",
"test_generation": "claude-3-5-sonnet-20241022",
# Analysis tasks
"code_review": "claude-3-sonnet-20240229",
"documentation": "claude-3-sonnet-20240229",
# Simple tasks
"formatting": "claude-3-haiku-20240307",
"simple_edits": "claude-3-haiku-20240307",
"quick_questions": "claude-3-haiku-20240307"
}
model = task_model_map.get(task_type, "claude-3-5-sonnet-20241022")
# Adjust for quality requirements
if quality_requirement == "maximum":
return "claude-3-opus-20240229"
elif quality_requirement == "fast":
return "claude-3-haiku-20240307"
return model
```
## Repository Overview
This is the Hanzo Python SDK monorepo containing the official Python client library for the Hanzo AI platform and related packages. The SDK provides unified access to 100+ LLM providers through a single OpenAI-compatible API interface, with enterprise features like cost tracking, rate limiting, and observability.
## Project Structure
This is a monorepo managed with `rye` containing multiple interconnected packages:
### Main Package
- **`pkg/hanzoai/`** - Core SDK for Hanzo AI platform
- OpenAI-compatible API client
- Support for 100+ LLM providers
- Cost tracking and rate limiting
- Team and organization management
- File operations and fine-tuning
### Sub-Packages (in `pkg/` directory)
- **`hanzo/`** - CLI and orchestration tools
- **`hanzo-mcp/`** - Model Context Protocol implementation
- **`hanzo-agents/`** - Agent framework and swarm orchestration
- **`hanzo-memory/`** - Memory and knowledge base management
- **`hanzo-network/`** - Distributed network capabilities
- **`hanzo-repl/`** - Interactive REPL for AI chat
- **`hanzo-aci/`** - AI code intelligence and editing tools
## Development Commands
### Setup and Installation
```bash
# Install Python via uv (required)
make install-python
# Complete setup (venv + dependencies)
make setup
# Install specific package for development
uv pip install -e .
uv pip install -e ./pkg/hanzo-agents
```
### Testing
```bash
# Run all tests
make test
./scripts/test
# Run specific test file
uv run pytest tests/api_resources/test_chat.py -v
# Run tests with specific pattern
uv run pytest -k "pattern" -v
# Run tests with coverage
uv run pytest --cov=hanzoai tests/
# Run tests for specific package
make test-agents # Test hanzo-agents
make test-mcp # Test hanzo-mcp
```
### Code Quality
```bash
# Format code
make format
ruff format pkg/
# Run linting
make lint
ruff check . --fix
# Type checking
make check-types
uv run mypy pkg/hanzoai --ignore-missing-imports
uv run pyright
```
### Building and Publishing
```bash
# Build all packages
make build
# Build specific package
uv build .
cd pkg/hanzo-mcp && uv build
# Check packages before publishing
make publish-check
```
## Architecture and Code Organization
### Client Architecture
The SDK uses a code-generated client architecture (via Stainless):
- **Base Client** (`_base_client.py`) - HTTP client with retry logic
- **Main Client** (`_client.py`) - `Hanzo` and `AsyncHanzo` classes
- **Resources** (`resources/`) - API endpoint implementations
- Each resource follows a consistent pattern with sync/async support
- Resources are organized by API domain (chat, files, models, etc.)
- **Types** (`types/`) - Pydantic models for request/response types
### Key Patterns
#### Resource Pattern
All API resources follow this structure:
```python
class ResourceWithRawResponse:
def __init__(self, resource: Resource) -> None:
self._resource = resource
# Expose methods with raw response wrapper
class AsyncResourceWithRawResponse:
# Async version of the above
```
#### Testing Pattern
Tests use `respx` for HTTP mocking (no external dependencies):
```python
@pytest.mark.respx(base_url=base_url)
def test_method(client: Hanzo, respx_mock: MockRouter) -> None:
respx_mock.get("/endpoint").mock(return_value=Response(200, json={}))
# Test implementation
```
### Important Implementation Details
1. **Environment Variables**:
- `HANZO_API_KEY` - API authentication
- `HANZO_BASE_URL` - API base URL (default: https://api.hanzo.ai)
- `HANZO_LOG` - Logging level (debug/info/warning/error)
2. **Dependency Management**:
- Uses `rye` for workspace management
- `uv` for fast Python package operations
- Separate lock files for production and dev dependencies
3. **Test Infrastructure**:
- All tests use mocked responses (no external API calls)
- 100% test coverage requirement
- Tests organized by resource in `tests/api_resources/`
4. **Code Generation**:
- Many files are auto-generated from OpenAPI spec
- Look for "File generated from our OpenAPI spec" header
- Manual changes to generated files will be overwritten
## Package-Specific Notes
### hanzo-mcp
- Implements Model Context Protocol for tool capabilities
- Includes filesystem, search, and agent delegation tools
- Can be installed to Claude Desktop with `make install-desktop`
### hanzo-agents
- Provides agent swarm orchestration
- Supports both hierarchical and peer network architectures
- Includes MCP tool integration for recursive agent calls
### hanzo CLI
- Main entry point: `hanzo.cli:main`
- Subcommands for auth, chat, mcp, network operations
- Supports local AI orchestration with `hanzo dev`
## Common Tasks
### Adding New API Endpoints
1. Update OpenAPI spec if using code generation
2. Add resource class in `resources/` directory
3. Add types in `types/` directory
4. Add tests in `tests/api_resources/`
5. Update `__init__.py` exports
### Running Local Development Server
```bash
# Start mock server for testing
python run_mock_server.py
# Run hanzo dev with local orchestration
hanzo dev --orchestrator local:llama-3.2-3b
```
### Debugging Tests
```bash
# Run with verbose output
uv run pytest -vv tests/
# Run with print statements visible
uv run pytest -s tests/
# Run specific test with debugging
uv run pytest tests/test_client.py::TestClient::test_method -vv
```
## CI/CD Pipeline
The repository uses GitHub Actions for CI:
- **Linting** - Runs on every push/PR with `ruff`
- **Testing** - Full test suite with coverage reporting
- **Type Checking** - Both `mypy` and `pyright`
- **Package Testing** - Separate CI for each sub-package
## Important Conventions
1. **No Print Statements**: Use logging instead, except in CLI tools
2. **Type Hints Required**: All functions must have type annotations
3. **Async Support**: All API methods have both sync and async versions
4. **Error Handling**: Use specific exception classes from `_exceptions.py`
5. **Documentation**: Docstrings for public APIs, examples in `/examples`
## Constitutional AI Principles
### Implementing Constitutional AI in Practice
```python
def apply_constitutional_ai(prompt: str, response: str) -> str:
"""Apply Constitutional AI principles to Claude's responses."""
constitutional_check = claude(
prompt=f"""
Original request: {prompt}
Initial response: {response}
Review this response against these principles:
1. Helpful: Does it genuinely help the user?
2. Harmless: Could it cause any harm?
3. Honest: Is it accurate and truthful?
If any issues, provide a revised response.
Otherwise, return "APPROVED".
""",
model="claude-3-opus-20240229"
)
if constitutional_check != "APPROVED":
return constitutional_check
return response
```
### Ethical Code Generation
```python
# Claude excels at considering ethical implications
ethical_result = claude(
prompt="""
Implement user data deletion feature.
Consider:
- GDPR compliance
- User privacy rights
- Data retention requirements
- Audit trail needs
- Cascading deletions
Explain ethical tradeoffs in your implementation.
""",
model="claude-3-opus-20240229"
)
```
## XML Tag Usage for Structured Thinking
### Structured Analysis Pattern
```python
# Claude responds well to XML-style structure
analysis_result = claude(
prompt="""
Analyze this codebase for refactoring opportunities.
<analysis_structure>
<code_smells>
Identify problematic patterns
</code_smells>
<architecture_issues>
Find architectural problems
</architecture_issues>
<performance_bottlenecks>
Locate performance issues
</performance_bottlenecks>
<security_vulnerabilities>
Identify security risks
</security_vulnerabilities>
<recommendations>
Provide prioritized fixes
</recommendations>
</analysis_structure>
Use the XML tags in your response.
""",
model="claude-3-opus-20240229"
)
```
### Thinking Tags Pattern
```python
# Use thinking tags for complex reasoning
reasoning_result = claude(
prompt="""
Design a distributed caching strategy.
<thinking>
Consider these aspects step by step:
- Cache invalidation strategies
- Consistency guarantees
- Network partition handling
- Performance implications
</thinking>
<solution>
Provide your recommended approach
</solution>
<implementation>
Show code examples
</implementation>
""",
model="claude-3-opus-20240229"
)
```
## Long Context Handling (200k tokens)
### Context Window Utilization
```python
class ClaudeLongContext:
"""Utilize Claude's 200k token context window."""
def __init__(self, model="claude-3-opus-20240229"):
self.model = model
self.max_tokens = 200_000
def analyze_large_pr(self, pr_files: dict):
"""Analyze large PR with many files."""
# Build comprehensive context
context = self.build_pr_context(pr_files)
return claude(
prompt=f"""
Review this pull request:
{context}
Provide:
1. Overall assessment
2. Security concerns
3. Performance implications
4. Breaking changes
5. Test coverage gaps
6. Specific file-by-file feedback
""",
model=self.model,
max_tokens=4000
)
def build_pr_context(self, files):
"""Build context from PR files."""
context_parts = []
for filepath, changes in files.items():
context_parts.append(f"""
<file path="{filepath}">
{changes}
</file>
""")
return "\n".join(context_parts)
```
### Conversation Memory Management
```python
class ClaudeConversationManager:
"""Manage long conversations with Claude."""
def __init__(self):
self.conversation_history = []
self.max_context = 190_000 # Leave room for response
def add_turn(self, user_msg: str, assistant_msg: str):
"""Add conversation turn."""
self.conversation_history.append({
"user": user_msg,
"assistant": assistant_msg,
"timestamp": time.time()
})
def get_relevant_context(self, new_query: str):
"""Get relevant conversation context."""
# Claude can handle full context
full_context = self.format_history()
if self.estimate_tokens(full_context) < self.max_context:
return full_context
# Smart truncation if needed
return self.smart_truncate(full_context, new_query)
def smart_truncate(self, context: str, query: str):
"""Intelligently truncate context."""
# Keep most relevant parts
return claude(
prompt=f"""
<context>
{context}
</context>
<new_query>
{query}
</new_query>
Extract the most relevant parts of the context
for answering the new query. Keep under 180k tokens.
""",
model="claude-3-haiku-20240307" # Use fast model
)
```
## Code Generation with Claude
### Claude's Code Generation Strengths
```python
# Claude excels at generating well-structured, documented code
code_result = claude(
prompt="""
Implement a rate limiter with these requirements:
- Token bucket algorithm
- Redis backend
- Async Python
- Per-user and per-IP limits
- Graceful degradation
Include:
1. Full implementation
2. Comprehensive docstrings
3. Type hints
4. Unit tests
5. Integration tests
6. Usage examples
""",
model="claude-3-5-sonnet-20241022",
temperature=0.3 # Lower for code generation
)
```
### Test Generation Pattern
```python
def generate_tests_with_claude(code: str):
"""Generate comprehensive tests with Claude."""
return claude(
prompt=f"""
Generate comprehensive tests for this code:
```python
{code}
```
Include:
<unit_tests>
- Test each function/method
- Edge cases
- Error conditions
- Mocking external dependencies
</unit_tests>
<integration_tests>
- End-to-end scenarios
- Real dependency tests
</integration_tests>
<property_tests>
- Property-based tests using hypothesis
</property_tests>
Use pytest framework with fixtures.
""",
model="claude-3-5-sonnet-20241022"
)
```
## Artifact Generation Patterns
### Documentation Artifacts
```python
# Claude can generate structured artifacts
docs_result = claude(
prompt="""
Create comprehensive documentation for this module.
Generate these artifacts:
1. README.md - Overview and quickstart
2. API.md - Full API reference
3. EXAMPLES.md - Usage examples
4. CONTRIBUTING.md - Contribution guide
Format as separate markdown sections.
""",
model="claude-3-sonnet-20240229"
)
```
### Configuration Generation
```python
# Generate complex configurations
config_result = claude(
prompt="""
Generate production-ready configurations:
1. docker-compose.yml - Full stack setup
2. .github/workflows/ci.yml - CI/CD pipeline
3. kubernetes/deployment.yaml - K8s deployment
4. terraform/main.tf - Infrastructure as code
Include security best practices and comments.
""",
model="claude-3-opus-20240229"
)
```
## Multi-Turn Conversation Management
### Stateful Conversations
```python
class ClaudeStatefulChat:
"""Manage stateful conversations with Claude."""
def __init__(self, model="claude-3-5-sonnet-20241022"):
self.model = model
self.messages = []
self.system_prompt = None
def set_system(self, prompt: str):
"""Set system prompt for conversation."""
self.system_prompt = prompt
def add_message(self, role: str, content: str):
"""Add message to conversation."""
self.messages.append({"role": role, "content": content})
def chat(self, user_input: str):
"""Continue conversation."""
self.add_message("user", user_input)
response = claude(
messages=self.messages,
system=self.system_prompt,
model=self.model
)
self.add_message("assistant", response)
return response
def reset_context(self, keep_system=True):
"""Reset conversation context."""
self.messages = []
if not keep_system:
self.system_prompt = None
```
## Analysis and Reasoning Capabilities
### Deep Code Analysis
```python
# Claude's superior reasoning for complex analysis
analysis = claude(
prompt="""
Perform deep analysis of this codebase:
<reasoning_steps>
1. Identify architectural patterns
2. Find hidden dependencies
3. Detect potential race conditions
4. Analyze error propagation
5. Evaluate test effectiveness
</reasoning_steps>
<provide>
- Detailed findings for each step
- Risk assessment
- Prioritized recommendations
</provide>
Think step by step, showing your reasoning.
""",
model="claude-3-opus-20240229"
)
```
### Comparative Analysis
```python
# Claude excels at nuanced comparisons
comparison = claude(
prompt="""
Compare these two implementation approaches:
<approach_1>
{code_1}
</approach_1>
<approach_2>
{code_2}
</approach_2>
Analyze:
- Performance characteristics
- Maintainability
- Scalability
- Error handling
- Testing complexity
Provide a balanced recommendation.
""",
model="claude-3-opus-20240229"
)
```
## Integration with Claude Desktop and MCP
### Claude Desktop Configuration
```json
{
"mcpServers": {
"hanzo-mcp": {
"command": "hanzo-mcp",
"args": ["serve"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-...",
"DEFAULT_CLAUDE_MODEL": "claude-3-5-sonnet-20241022"
}
}
}
}
```
### MCP Tool Usage Patterns
```python
# Claude with MCP tools
result = claude(
prompt="""
Using available MCP tools:
1. Search for authentication patterns
2. Read the main auth module
3. Suggest improvements
4. Generate updated implementation
""",
enable_tools=True,
tools=["search", "read", "write"]
)
```
## Claude CLI Tool Usage
### Basic CLI Usage
```bash
# Direct Claude invocation
claude "Analyze this Python module for improvements"
# With specific model
claude --model claude-3-opus-20240229 "Design system architecture"
# With system prompt
claude --system "You are a security expert" "Audit this code for vulnerabilities"
```
### Advanced CLI Patterns
```bash
# Multi-file analysis
claude --files "*.py" "Review all Python files for consistency"
# Interactive mode
claude --interactive --model claude-3-5-sonnet-20241022
# With context from previous conversation
claude --continue-from session-123 "What about the error handling?"
```
## Best Practices for Claude
### 1. Model Selection
```python
# Choose based on task requirements
if needs_deep_reasoning:
model = "claude-3-opus-20240229"
elif needs_code_generation:
model = "claude-3-5-sonnet-20241022"
elif needs_speed:
model = "claude-3-haiku-20240307"
else:
model = "claude-3-sonnet-20240229"
```
### 2. Prompt Engineering
- Use XML tags for structure
- Include thinking steps for complex reasoning
- Provide clear output format specifications
- Use Constitutional AI principles
### 3. Context Management
- Leverage full 200k context when beneficial
- Use conversation history effectively
- Implement smart truncation when needed
### 4. Error Handling
```python
try:
result = claude(prompt=prompt, model=model)
except AnthropicError as e:
if "rate_limit" in str(e):
# Wait and retry
time.sleep(60)
result = claude(prompt=prompt, model="claude-3-haiku-20240307")
elif "context_length" in str(e):
# Truncate and retry
truncated_prompt = prompt[:50000]
result = claude(prompt=truncated_prompt, model=model)
else:
raise
```
### 5. Cost Optimization
- Use Haiku for simple tasks
- Cache frequently used responses
- Batch similar requests
- Monitor token usage
## Integration with Hanzo SDK
### Using Claude through Hanzo
```python
from hanzoai import Hanzo
client = Hanzo(api_key="your-key")
# Use Claude through unified interface
response = client.chat.completions.create(
model="claude-3-5-sonnet-20241022",
messages=[
{"role": "user", "content": "Your prompt"}
],
max_tokens=4000,
temperature=0.7
)
```
### Claude-Specific Features
```python
# System prompts (Claude-specific)
response = client.chat.completions.create(
model="claude-3-opus-20240229",
system="You are an expert code reviewer",
messages=[{"role": "user", "content": "Review this code"}]
)
# Streaming responses
stream = client.chat.completions.create(
model="claude-3-5-sonnet-20241022",
messages=[{"role": "user", "content": "Generate code"}],
stream=True
)
for chunk in stream:
print(chunk.choices[0].delta.content, end="")
```
This comprehensive guide enables effective use of Claude models for development workflows in the Hanzo Python SDK project.
GEMINI.md
-701
View File
@@ -1,701 +0,0 @@
# Gemini-Specific Workflow Patterns
## Overview
This document provides comprehensive patterns for working with Google's Gemini models through hanzo-mcp. It covers the Gemini model family, multimodal capabilities, and optimizations specific to Gemini's strengths.
## Gemini Model Family
### Model Tiers
```python
GEMINI_MODELS = {
# Ultra Tier - Most capable
"gemini-1.5-ultra": {
"context_window": 2_097_152, # 2M tokens
"strengths": ["complex reasoning", "multimodal", "long context"],
"cost_tier": "premium",
"best_for": ["architecture design", "comprehensive analysis"]
},
# Pro Tier - Balanced performance
"gemini-1.5-pro": {
"context_window": 2_097_152, # 2M tokens
"strengths": ["reasoning", "code generation", "multimodal"],
"cost_tier": "balanced",
"best_for": ["general development", "code review", "documentation"]
},
"gemini-1.0-pro": {
"context_window": 32_768,
"strengths": ["text generation", "reasoning"],
"cost_tier": "balanced",
"best_for": ["standard tasks", "quick responses"]
},
# Flash Tier - Fast and efficient
"gemini-1.5-flash": {
"context_window": 1_048_576, # 1M tokens
"strengths": ["speed", "efficiency", "multimodal"],
"cost_tier": "budget",
"best_for": ["quick tasks", "high volume", "real-time responses"]
},
"gemini-1.5-flash-8b": {
"context_window": 1_048_576, # 1M tokens
"strengths": ["ultra-fast", "low latency"],
"cost_tier": "economy",
"best_for": ["simple tasks", "formatting", "extraction"]
}
}
```
### Model Selection Strategy
```python
def select_gemini_model(task_type: str, context_size: int, budget: str = "balanced"):
"""Select optimal Gemini model for task."""
if context_size > 32_768:
# Need long context support
if budget == "premium":
return "gemini-1.5-ultra"
elif budget == "balanced":
return "gemini-1.5-pro"
else:
return "gemini-1.5-flash"
# Standard context tasks
task_model_map = {
"architecture": "gemini-1.5-pro",
"code_generation": "gemini-1.5-pro",
"code_review": "gemini-1.5-pro",
"documentation": "gemini-1.5-flash",
"formatting": "gemini-1.5-flash-8b",
"extraction": "gemini-1.5-flash-8b",
"analysis": "gemini-1.5-pro",
"multimodal": "gemini-1.5-pro"
}
return task_model_map.get(task_type, "gemini-1.5-flash")
```
## Multimodal Capabilities
### Text + Image Analysis
```python
# Using Gemini for code screenshot analysis
result = gemini(
prompt="""
Analyze this code screenshot:
- Identify the programming language
- Explain what the code does
- Suggest improvements
- Find potential bugs
""",
images=["path/to/code_screenshot.png"],
model="gemini-1.5-pro"
)
```
### Video Analysis
```python
# Analyze code walkthrough video
result = gemini(
prompt="""
Watch this code review video and:
1. Summarize the main points
2. List all mentioned issues
3. Extract action items
4. Note design decisions
""",
video="path/to/review_video.mp4",
model="gemini-1.5-pro"
)
```
### Audio Processing
```python
# Transcribe and analyze meeting recording
result = gemini(
prompt="""
Process this technical discussion:
1. Transcribe the conversation
2. Extract technical decisions
3. List action items by person
4. Summarize architecture choices
""",
audio="path/to/meeting.mp3",
model="gemini-1.5-flash"
)
```
### Combined Multimodal
```python
# Analyze multiple inputs together
result = gemini(
prompt="""
Based on the whiteboard image, code files, and audio explanation:
1. Create implementation plan
2. Identify potential issues
3. Suggest optimizations
4. Generate documentation
""",
images=["whiteboard.jpg"],
text_files=["main.py", "config.yaml"],
audio="explanation.mp3",
model="gemini-1.5-ultra"
)
```
## Long Context Window Strategies
### 2M Token Context Utilization
```python
class GeminiLongContext:
"""Utilize Gemini's 2M token context window."""
def __init__(self, model="gemini-1.5-pro"):
self.model = model
self.max_tokens = 2_097_152
def analyze_entire_codebase(self, repo_path: str):
"""Analyze entire repository in single context."""
# Collect all code files
code_files = self.collect_files(repo_path)
# Build massive context
context = self.build_context(code_files)
# Single comprehensive analysis
return gemini(
prompt=f"""
Analyze this entire codebase:
{context}
Provide:
1. Architecture overview
2. Design patterns used
3. Security vulnerabilities
4. Performance bottlenecks
5. Refactoring opportunities
6. Missing tests
7. Documentation gaps
""",
model=self.model,
max_tokens=8000 # Large response
)
def build_context(self, files):
"""Build context from files."""
context_parts = []
for file_path, content in files.items():
context_parts.append(f"""
=== File: {file_path} ===
{content}
""")
return "\n\n".join(context_parts)
```
### Context Window Management
```python
def optimize_gemini_context(files: dict, max_context: int = 2_000_000):
"""Optimize context for Gemini's window."""
# Priority ordering
priority_order = [
".py", # Python files first
".ts", # TypeScript
".js", # JavaScript
".md", # Documentation
".yaml", # Config
".json", # Data files
]
sorted_files = []
for ext in priority_order:
sorted_files.extend([
(path, content)
for path, content in files.items()
if path.endswith(ext)
])
# Build context up to limit
context = []
current_size = 0
for path, content in sorted_files:
file_size = len(content) // 4 # Rough token estimate
if current_size + file_size > max_context:
break
context.append(f"File: {path}\n{content}")
current_size += file_size
return "\n\n".join(context)
```
## Code Generation Optimizations
### Gemini Code Generation Patterns
```python
# Optimized code generation prompt
code_result = gemini(
prompt="""
Generate Python implementation for user authentication:
Requirements:
- JWT tokens with RS256
- Redis session storage
- Rate limiting per IP
- Password complexity validation
- 2FA support
Style Guidelines:
- Use type hints
- Add comprehensive docstrings
- Include error handling
- Follow PEP 8
Include:
1. Main implementation
2. Unit tests
3. Integration tests
4. Usage examples
""",
model="gemini-1.5-pro",
temperature=0.4, # Focused generation
response_mime_type="text/x-python" # Gemini-specific
)
```
### Multi-File Generation
```python
def generate_module_with_gemini(module_name: str, requirements: str):
"""Generate complete module with Gemini."""
result = gemini(
prompt=f"""
Create a complete Python module '{module_name}' with these requirements:
{requirements}
Generate these files:
1. __init__.py - Package initialization
2. models.py - Data models
3. services.py - Business logic
4. api.py - API endpoints
5. utils.py - Helper functions
6. tests/test_{module_name}.py - Tests
7. README.md - Documentation
Use markdown code blocks with filenames:
```python:filename.py
code here
```
""",
model="gemini-1.5-pro",
temperature=0.3
)
# Parse and save files
files = parse_gemini_multifile_response(result)
return files
```
## Integration with Google Cloud Services
### Vertex AI Integration
```python
from google.cloud import aiplatform
from hanzoai import Hanzo
class GeminiVertex:
"""Gemini through Vertex AI."""
def __init__(self, project_id: str, location: str = "us-central1"):
self.project_id = project_id
self.location = location
aiplatform.init(project=project_id, location=location)
# Also use through Hanzo
self.hanzo = Hanzo(
api_key=os.getenv("HANZO_API_KEY")
)
async def generate(self, prompt: str, model: str = "gemini-1.5-pro"):
"""Generate using Vertex AI or Hanzo."""
try:
# Try Vertex AI first (better quotas)
response = await self.vertex_generate(prompt, model)
except Exception:
# Fallback to Hanzo
response = await self.hanzo.chat.completions.create(
model=f"vertex/{model}",
messages=[{"role": "user", "content": prompt}]
)
return response
```
### Google Cloud Storage Integration
```python
def analyze_gcs_codebase(bucket_name: str, prefix: str = ""):
"""Analyze code directly from GCS."""
# List all files in bucket
files = list_gcs_files(bucket_name, prefix)
# Build GCS URLs
file_urls = [
f"gs://{bucket_name}/{file}"
for file in files
]
# Gemini can read GCS directly
result = gemini(
prompt="""
Analyze this codebase from Google Cloud Storage.
Provide comprehensive architecture review.
""",
files=file_urls, # GCS URLs
model="gemini-1.5-pro"
)
return result
```
## Cost-Performance Tradeoffs
### Cost Optimization Strategy
```python
class GeminiCostOptimizer:
"""Optimize Gemini usage costs."""
def __init__(self):
self.cost_per_1k_tokens = {
"gemini-1.5-ultra": {"input": 0.007, "output": 0.021},
"gemini-1.5-pro": {"input": 0.0035, "output": 0.0105},
"gemini-1.5-flash": {"input": 0.00035, "output": 0.00105},
"gemini-1.5-flash-8b": {"input": 0.0001, "output": 0.0003}
}
def select_by_budget(self, task: str, max_cost: float):
"""Select model within budget."""
estimated_tokens = self.estimate_tokens(task)
for model, costs in self.cost_per_1k_tokens.items():
estimated_cost = (
(estimated_tokens["input"] / 1000) * costs["input"] +
(estimated_tokens["output"] / 1000) * costs["output"]
)
if estimated_cost <= max_cost:
return model
return "gemini-1.5-flash-8b" # Cheapest fallback
def batch_optimize(self, tasks: list):
"""Optimize batch processing."""
# Group by complexity
simple_tasks = [t for t in tasks if t["complexity"] == "simple"]
complex_tasks = [t for t in tasks if t["complexity"] == "complex"]
# Use Flash for simple tasks
if simple_tasks:
gemini(
prompt=self.batch_prompt(simple_tasks),
model="gemini-1.5-flash-8b"
)
# Use Pro for complex tasks
if complex_tasks:
gemini(
prompt=self.batch_prompt(complex_tasks),
model="gemini-1.5-pro"
)
```
## Gemini-Specific Prompt Formats
### Structured Prompts
```python
def create_gemini_prompt(
instruction: str,
context: str = None,
examples: list = None,
constraints: list = None,
output_format: str = None
):
"""Create optimized Gemini prompt."""
prompt_parts = []
# Gemini responds well to clear sections
prompt_parts.append(f"## Instruction\n{instruction}")
if context:
prompt_parts.append(f"## Context\n{context}")
if examples:
prompt_parts.append("## Examples")
for i, example in enumerate(examples, 1):
prompt_parts.append(f"### Example {i}")
prompt_parts.append(f"Input: {example['input']}")
prompt_parts.append(f"Output: {example['output']}")
if constraints:
prompt_parts.append("## Constraints")
for constraint in constraints:
prompt_parts.append(f"- {constraint}")
if output_format:
prompt_parts.append(f"## Output Format\n{output_format}")
return "\n\n".join(prompt_parts)
```
### Chain of Thought Prompting
```python
# Gemini excels at step-by-step reasoning
cot_result = gemini(
prompt="""
Solve this algorithm problem step by step:
Problem: [problem description]
Think through this methodically:
1. Understand the problem
2. Identify the algorithm type
3. Consider edge cases
4. Design the solution
5. Implement in Python
6. Analyze time complexity
7. Optimize if possible
Show your reasoning for each step.
""",
model="gemini-1.5-pro",
temperature=0.2
)
```
## Function Calling Patterns
### Gemini Function Calling
```python
# Define functions for Gemini
functions = [
{
"name": "execute_code",
"description": "Execute Python code and return results",
"parameters": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Python code to execute"
}
},
"required": ["code"]
}
},
{
"name": "search_documentation",
"description": "Search project documentation",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
},
"file_pattern": {
"type": "string",
"description": "File pattern to search"
}
},
"required": ["query"]
}
}
]
# Use with function calling
result = gemini(
prompt="Find and fix the authentication bug",
model="gemini-1.5-pro",
functions=functions,
function_call="auto" # Let Gemini decide when to call
)
```
### Tool Use Patterns
```python
def gemini_with_tools(task: str):
"""Use Gemini with tool access."""
return gemini(
prompt=f"""
Task: {task}
You have access to these tools:
- search: Search codebase
- read: Read files
- execute: Run code
- test: Run tests
Use tools as needed to complete the task.
Call tools using: TOOL[tool_name](arguments)
""",
model="gemini-1.5-pro",
enable_tool_use=True
)
```
## Safety Settings and Content Filtering
### Configure Safety Settings
```python
SAFETY_SETTINGS = {
"harassment": "BLOCK_NONE",
"hate_speech": "BLOCK_NONE",
"sexually_explicit": "BLOCK_NONE",
"dangerous_content": "BLOCK_ONLY_HIGH"
}
# Apply safety settings
result = gemini(
prompt="Analyze security vulnerabilities",
model="gemini-1.5-pro",
safety_settings=SAFETY_SETTINGS
)
```
### Content Filtering for Code
```python
def gemini_code_review(code: str):
"""Review code with appropriate filters."""
# Disable filters for code review
# Code might contain security examples
return gemini(
prompt=f"""
Review this code for security issues:
```python
{code}
```
Include:
- SQL injection vulnerabilities
- XSS possibilities
- Authentication bypasses
- Cryptographic weaknesses
""",
model="gemini-1.5-pro",
safety_settings={
"dangerous_content": "BLOCK_NONE" # Allow security discussion
}
)
```
## Best Practices for Gemini
### 1. Model Selection
```python
# Choose model based on task requirements
if needs_multimodal:
model = "gemini-1.5-pro"
elif needs_long_context:
model = "gemini-1.5-pro" if budget else "gemini-1.5-flash"
elif needs_speed:
model = "gemini-1.5-flash-8b"
else:
model = "gemini-1.5-flash"
```
### 2. Prompt Optimization
- Use clear section headers
- Provide structured examples
- Leverage chain-of-thought for complex reasoning
- Include explicit output format specifications
### 3. Context Management
- Utilize full 2M token window when beneficial
- Prioritize relevant files in context
- Use file references for large codebases
### 4. Cost Optimization
- Use Flash models for simple tasks
- Batch similar requests
- Cache frequently used responses
- Monitor token usage
### 5. Error Handling
```python
try:
result = gemini(prompt=prompt, model=model)
except GoogleAPIError as e:
if "quota_exceeded" in str(e):
# Switch to different model
result = gemini(prompt=prompt, model="gemini-1.5-flash")
elif "safety_filter" in str(e):
# Adjust safety settings
result = gemini(
prompt=prompt,
model=model,
safety_settings=relaxed_settings
)
else:
raise
```
## Integration with Hanzo MCP
### Using Gemini CLI Tool
```bash
# Direct Gemini invocation
gemini "Analyze this Python module for improvements"
# With specific model
gemini --model gemini-1.5-ultra "Design system architecture"
# With multimodal inputs
gemini --image diagram.png "Explain this architecture diagram"
```
### Using LLM Tool with Gemini
```bash
# Single Gemini query
llm --action query \
--model gemini-1.5-pro \
--prompt "Generate comprehensive test suite"
# Gemini in consensus
llm --action consensus \
--models '["gemini-1.5-pro", "claude-3-opus", "gpt-4"]' \
--prompt "Design decision: microservices vs monolith"
```
### Gemini in Agent Workflows
```python
# Use Gemini for specific agent tasks
agent(
prompt="Implement feature with tests",
model="gemini-1.5-pro", # Specify Gemini
tools=["read", "write", "test"]
)
# Gemini in swarm
swarm(
agents=[
{"role": "architect", "model": "gemini-1.5-ultra"},
{"role": "coder", "model": "gemini-1.5-pro"},
{"role": "tester", "model": "gemini-1.5-flash"}
]
)
```
This comprehensive guide enables effective use of Gemini models for development workflows in the Hanzo Python SDK project.