File size: 10,330 Bytes
1041734 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 | """
Vision Tool - Image analysis using multimodal LLMs
Author: @mangobee
Date: 2026-01-02
Provides image analysis functionality using:
- Gemini 2.0 Flash (default, free tier)
- Claude Sonnet 4.5 (fallback, if configured)
Supports:
- Image file loading and encoding
- Question answering about images
- Object detection/description
- Text extraction (OCR)
- Visual reasoning
"""
import base64
import logging
from pathlib import Path
from typing import Dict, Optional
from tenacity import (
retry,
stop_after_attempt,
wait_exponential,
retry_if_exception_type,
)
from src.config.settings import Settings
# ============================================================================
# CONFIG
# ============================================================================
MAX_RETRIES = 3
RETRY_MIN_WAIT = 1 # seconds
RETRY_MAX_WAIT = 10 # seconds
MAX_IMAGE_SIZE_MB = 10 # Maximum image size in MB
SUPPORTED_IMAGE_FORMATS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
# ============================================================================
# Logging Setup
# ============================================================================
logger = logging.getLogger(__name__)
# ============================================================================
# Image Loading and Encoding
# ============================================================================
def load_and_encode_image(image_path: str) -> Dict[str, str]:
"""
Load image file and encode as base64.
Args:
image_path: Path to image file
Returns:
Dict with structure: {
"data": str, # Base64 encoded image
"mime_type": str, # MIME type (e.g., "image/jpeg")
"size_mb": float, # File size in MB
}
Raises:
FileNotFoundError: If image doesn't exist
ValueError: If file is not a supported image format or too large
"""
path = Path(image_path)
if not path.exists():
raise FileNotFoundError(f"Image file not found: {image_path}")
# Check file extension
extension = path.suffix.lower()
if extension not in SUPPORTED_IMAGE_FORMATS:
raise ValueError(
f"Unsupported image format: {extension}. "
f"Supported: {', '.join(SUPPORTED_IMAGE_FORMATS)}"
)
# Check file size
size_bytes = path.stat().st_size
size_mb = size_bytes / (1024 * 1024)
if size_mb > MAX_IMAGE_SIZE_MB:
raise ValueError(
f"Image too large: {size_mb:.2f}MB. Maximum: {MAX_IMAGE_SIZE_MB}MB"
)
# Read and encode image
with open(path, 'rb') as f:
image_data = f.read()
encoded = base64.b64encode(image_data).decode('utf-8')
# Determine MIME type
mime_types = {
'.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg',
'.png': 'image/png',
'.gif': 'image/gif',
'.webp': 'image/webp',
'.bmp': 'image/bmp',
}
mime_type = mime_types.get(extension, 'image/jpeg')
logger.info(f"Image loaded: {path.name} ({size_mb:.2f}MB, {mime_type})")
return {
"data": encoded,
"mime_type": mime_type,
"size_mb": size_mb,
}
# ============================================================================
# Gemini Vision
# ============================================================================
@retry(
stop=stop_after_attempt(MAX_RETRIES),
wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
retry=retry_if_exception_type((ConnectionError, TimeoutError)),
reraise=True,
)
def analyze_image_gemini(image_path: str, question: Optional[str] = None) -> Dict:
"""
Analyze image using Gemini 2.0 Flash.
Args:
image_path: Path to image file
question: Optional question about the image (default: "Describe this image")
Returns:
Dict with structure: {
"answer": str, # LLM's analysis/answer
"model": "gemini-2.0-flash",
"image_path": str,
"question": str
}
Raises:
ValueError: If API key not configured or image invalid
ConnectionError: If API connection fails (triggers retry)
"""
try:
import google.genai as genai
settings = Settings()
api_key = settings.google_api_key
if not api_key:
raise ValueError("GOOGLE_API_KEY not configured in settings")
# Load and encode image
image_data = load_and_encode_image(image_path)
# Default question
if not question:
question = "Describe this image in detail."
logger.info(f"Gemini vision analysis: {Path(image_path).name} - '{question}'")
# Configure Gemini client
client = genai.Client(api_key=api_key)
# Create content with image and text
response = client.models.generate_content(
model='gemini-2.0-flash-exp',
contents=[
question,
{
"mime_type": image_data["mime_type"],
"data": image_data["data"]
}
]
)
answer = response.text.strip()
logger.info(f"Gemini vision successful: {len(answer)} chars")
return {
"answer": answer,
"model": "gemini-2.0-flash",
"image_path": image_path,
"question": question,
}
except ValueError as e:
logger.error(f"Gemini configuration/input error: {e}")
raise
except (ConnectionError, TimeoutError) as e:
logger.warning(f"Gemini connection error (will retry): {e}")
raise
except Exception as e:
logger.error(f"Gemini vision error: {e}")
raise Exception(f"Gemini vision failed: {str(e)}")
# ============================================================================
# Claude Vision (Fallback)
# ============================================================================
@retry(
stop=stop_after_attempt(MAX_RETRIES),
wait=wait_exponential(multiplier=1, min=RETRY_MIN_WAIT, max=RETRY_MAX_WAIT),
retry=retry_if_exception_type((ConnectionError, TimeoutError)),
reraise=True,
)
def analyze_image_claude(image_path: str, question: Optional[str] = None) -> Dict:
"""
Analyze image using Claude Sonnet 4.5.
Args:
image_path: Path to image file
question: Optional question about the image (default: "Describe this image")
Returns:
Dict with structure: {
"answer": str, # LLM's analysis/answer
"model": "claude-sonnet-4.5",
"image_path": str,
"question": str
}
Raises:
ValueError: If API key not configured or image invalid
ConnectionError: If API connection fails (triggers retry)
"""
try:
from anthropic import Anthropic
settings = Settings()
api_key = settings.anthropic_api_key
if not api_key:
raise ValueError("ANTHROPIC_API_KEY not configured in settings")
# Load and encode image
image_data = load_and_encode_image(image_path)
# Default question
if not question:
question = "Describe this image in detail."
logger.info(f"Claude vision analysis: {Path(image_path).name} - '{question}'")
# Configure Claude client
client = Anthropic(api_key=api_key)
# Create message with image
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_data["mime_type"],
"data": image_data["data"],
},
},
{
"type": "text",
"text": question
}
],
}
],
)
answer = response.content[0].text.strip()
logger.info(f"Claude vision successful: {len(answer)} chars")
return {
"answer": answer,
"model": "claude-sonnet-4.5",
"image_path": image_path,
"question": question,
}
except ValueError as e:
logger.error(f"Claude configuration/input error: {e}")
raise
except (ConnectionError, TimeoutError) as e:
logger.warning(f"Claude connection error (will retry): {e}")
raise
except Exception as e:
logger.error(f"Claude vision error: {e}")
raise Exception(f"Claude vision failed: {str(e)}")
# ============================================================================
# Unified Vision Analysis
# ============================================================================
def analyze_image(image_path: str, question: Optional[str] = None) -> Dict:
"""
Analyze image using available multimodal LLM.
Tries Gemini first (free tier), falls back to Claude if configured.
Args:
image_path: Path to image file
question: Optional question about the image
Returns:
Dict with analysis results from either Gemini or Claude
Raises:
Exception: If both Gemini and Claude fail or are not configured
"""
settings = Settings()
# Try Gemini first (default, free tier)
if settings.google_api_key:
try:
return analyze_image_gemini(image_path, question)
except Exception as e:
logger.warning(f"Gemini failed, trying Claude: {e}")
# Fallback to Claude
if settings.anthropic_api_key:
try:
return analyze_image_claude(image_path, question)
except Exception as e:
logger.error(f"Claude also failed: {e}")
raise Exception(f"Vision analysis failed - Gemini and Claude both failed")
# No API keys configured
raise ValueError(
"No vision API configured. Please set GOOGLE_API_KEY or ANTHROPIC_API_KEY"
)
|