feat: update Google Gemini models and improve error handling

- Update default model from gemini-1.5-flash to gemini-2.5-flash
- Increase default max_tokens from 2000 to 8192 for Gemini 2.5 models
- Add support for model selection via environment variables (PDODB_AI_<PROVIDER>_MODEL)
- Improve Google API error handling with detailed finishReason checks
- Handle MAX_TOKENS, SAFETY, RECITATION finish reasons gracefully
- Return partial content with warning when response is truncated
- Update documentation with latest available Gemini models
- Add helper script check-google-models.php for model discovery

Author: tommyknocker

README.md

@@ -489,6 +489,8 @@ Or use CLI:
 ```bash
 # Set API key
 export PDODB_AI_OPENAI_KEY=sk-...
+export PDODB_AI_OPENAI_MODEL=gpt-4o-mini  # Optional: gpt-4, gpt-3.5-turbo
+export PDODB_AI_GOOGLE_MODEL=gemini-2.5-flash  # Optional: gemini-2.5-pro, gemini-2.0-flash-001, gemini-flash-latest
 
 # Analyze query
 pdodb ai analyze "SELECT * FROM users WHERE email = '[email protected]'" \
@@ -498,6 +500,8 @@ pdodb ai analyze "SELECT * FROM users WHERE email = '[email protected]'" \
 
 **Supported Providers:** OpenAI, Anthropic, Google, Microsoft, Ollama (local, no API key)
 
+**Model Selection:** Configure models via environment variables (`PDODB_AI_<PROVIDER>_MODEL`) or config array (`ai.providers.<provider>.model`)
+
 See [AI Analysis Documentation](documentation/05-advanced-features/23-ai-analysis.md) for complete guide.
 
 ### Basic CRUD Operations

documentation/05-advanced-features/23-ai-analysis.md

@@ -30,7 +30,7 @@ PDOdb supports multiple AI providers, each with their own strengths:
 |----------|--------|----------|------------------|
 | **OpenAI** | gpt-4o-mini, gpt-4, gpt-3.5-turbo | General analysis, fast responses | Yes |
 | **Anthropic** | claude-3-5-sonnet, claude-3-opus | Detailed analysis, long context | Yes |
-| **Google** | gemini-pro, gemini-ultra | Multimodal analysis | Yes |
+| **Google** | gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash-001, gemini-flash-latest, gemini-pro-latest | Multimodal analysis, large context | Yes |
 | **Microsoft** | Azure OpenAI models | Enterprise environments | Yes |
 | **Ollama** | Any local model (llama2, deepseek-coder, etc.) | Privacy, offline use, no API costs | No |
 
@@ -52,13 +52,22 @@ export PDODB_AI_ANTHROPIC_KEY=sk-ant-...
 
 # Google
 export PDODB_AI_GOOGLE_KEY=...
+export PDODB_AI_GOOGLE_MODEL=gemini-2.5-flash  # Optional: gemini-2.5-pro, gemini-2.0-flash-001, gemini-flash-latest, gemini-pro-latest
 
 # Microsoft Azure OpenAI
 export PDODB_AI_MICROSOFT_KEY=...
+export PDODB_AI_MICROSOFT_MODEL=gpt-4  # Optional: model name
 # Also configure endpoint via config array (see below)
 
 # Ollama (local, no API key needed)
 export PDODB_AI_OLLAMA_URL=http://localhost:11434
+export PDODB_AI_OLLAMA_MODEL=llama3.2  # Optional: model name
+
+# OpenAI
+export PDODB_AI_OPENAI_MODEL=gpt-4o-mini  # Optional: gpt-4, gpt-3.5-turbo
+
+# Anthropic
+export PDODB_AI_ANTHROPIC_MODEL=claude-3-5-sonnet-20241022  # Optional: claude-3-opus
 ```
 
 ### Configuration Array
@@ -88,15 +97,41 @@ $db = new PdoDb('mysql', [
                 'model' => 'claude-3-5-sonnet-20241022',
                 'temperature' => 0.7,
             ],
+            'google' => [
+                'model' => 'gemini-2.5-flash',  # or gemini-2.5-pro, gemini-2.0-flash-001, gemini-flash-latest, gemini-pro-latest
+                'temperature' => 0.7,
+                'max_tokens' => 2000,
+            ],
             'microsoft' => [
                 'endpoint' => 'https://your-resource.openai.azure.com',
                 'deployment' => 'gpt-4',
             ],
+            'ollama' => [
+                'model' => 'llama3.2',  # or any local model name
+            ],
         ],
     ],
 ]);
 ```
 
+### Available Google Gemini Models
+
+Google provides multiple model variants. Recommended models:
+
+- **gemini-2.5-flash** (default) - Stable, fast, versatile model with 1M token context
+- **gemini-2.5-pro** - Best for complex tasks, 1M token context, 65K output tokens
+- **gemini-2.0-flash-001** - Stable version of Gemini 2.0 Flash (January 2025)
+- **gemini-flash-latest** - Always uses the latest Flash model
+- **gemini-pro-latest** - Always uses the latest Pro model
+
+For a complete list of available models, use the provided script:
+
+```bash
+php check-google-models.php
+```
+
+This script will show all models that support `generateContent` with their token limits and descriptions.
+
 ### Priority
 
 Configuration priority (highest to lowest):

src/ai/AiConfig.php

@@ -110,6 +110,24 @@ protected function loadFromEnvironment(): void
         } else {
             $this->ollamaUrl = 'http://localhost:11434';
         }
+
+        // Load provider-specific model settings from environment variables
+        $this->loadProviderModelsFromEnvironment();
+    }
+
+    /**
+     * Load provider model settings from environment variables.
+     */
+    protected function loadProviderModelsFromEnvironment(): void
+    {
+        $providers = ['openai', 'anthropic', 'google', 'microsoft', 'ollama'];
+        foreach ($providers as $provider) {
+            $envVar = 'PDODB_AI_' . strtoupper($provider) . '_MODEL';
+            $model = getenv($envVar);
+            if ($model !== false && $model !== '') {
+                $this->setProviderSetting($provider, 'model', $model);
+            }
+        }
     }
 
     /**

src/ai/providers/GoogleProvider.php

@@ -13,9 +13,9 @@
 class GoogleProvider extends BaseAiProvider
 {
     private const string API_URL = 'https://generativelanguage.googleapis.com/v1beta/models/%s:generateContent'; // v1beta is the latest supported version
-    private const string DEFAULT_MODEL = 'gemini-pro';
+    private const string DEFAULT_MODEL = 'gemini-2.5-flash';
     private const float DEFAULT_TEMPERATURE = 0.7;
-    private const int DEFAULT_MAX_TOKENS = 2000;
+    private const int DEFAULT_MAX_TOKENS = 8192; // Increased default for Gemini 2.5 models (supports up to 65K output tokens)
     private const string URL_PARAM_KEY = '?key=';
     private const string REQUEST_KEY_CONTENTS = 'contents';
     private const string REQUEST_KEY_PARTS = 'parts';
@@ -112,14 +112,96 @@ protected function callApi(string $prompt, string $systemInstruction): string
 
         $response = $this->makeRequest($url, $data);
 
-        if (!isset($response[self::RESPONSE_KEY_CANDIDATES][0][self::RESPONSE_KEY_CONTENT][self::REQUEST_KEY_PARTS][0][self::REQUEST_KEY_TEXT])) {
+        // Check for error in response
+        if (isset($response['error'])) {
+            $errorCode = $response['error']['code'] ?? 'unknown';
+            $errorMessage = $response['error']['message'] ?? 'Unknown error';
             throw new QueryException(
-                'Invalid response format from Google API',
+                "Google API error ({$errorCode}): {$errorMessage}",
                 0
             );
         }
 
-        return (string)$response[self::RESPONSE_KEY_CANDIDATES][0][self::RESPONSE_KEY_CONTENT][self::REQUEST_KEY_PARTS][0][self::REQUEST_KEY_TEXT];
+        // Validate response structure
+        if (!isset($response[self::RESPONSE_KEY_CANDIDATES])) {
+            $responseJson = json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+            $responseStr = is_string($responseJson) ? substr($responseJson, 0, 500) : 'Unable to encode response';
+            throw new QueryException(
+                'Invalid response format from Google API: missing "candidates" key. Response: ' . $responseStr,
+                0
+            );
+        }
+
+        if (empty($response[self::RESPONSE_KEY_CANDIDATES])) {
+            $responseJson = json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+            $responseStr = is_string($responseJson) ? substr($responseJson, 0, 500) : 'Unable to encode response';
+            throw new QueryException(
+                'Invalid response format from Google API: empty "candidates" array. Response: ' . $responseStr,
+                0
+            );
+        }
+
+        $candidate = $response[self::RESPONSE_KEY_CANDIDATES][0];
+
+        // Check finish reason
+        $finishReason = $candidate['finishReason'] ?? null;
+        if ($finishReason !== null && $finishReason !== 'STOP') {
+            $reasonMessages = [
+                'MAX_TOKENS' => 'Response was truncated due to token limit. Consider increasing max_tokens.',
+                'SAFETY' => 'Response was blocked due to safety filters.',
+                'RECITATION' => 'Response was blocked due to recitation detection.',
+                'OTHER' => 'Response was stopped for an unknown reason.',
+            ];
+            $message = $reasonMessages[$finishReason] ?? "Response was stopped (reason: {$finishReason}).";
+            
+            // Try to get partial content if available
+            $content = $candidate[self::RESPONSE_KEY_CONTENT] ?? null;
+            if ($content !== null && isset($content[self::REQUEST_KEY_PARTS]) && !empty($content[self::REQUEST_KEY_PARTS])) {
+                $part = $content[self::REQUEST_KEY_PARTS][0];
+                if (isset($part[self::REQUEST_KEY_TEXT])) {
+                    // Return partial content with warning
+                    return (string)$part[self::REQUEST_KEY_TEXT] . "\n\n[Note: Response was truncated. {$message}]";
+                }
+            }
+            
+            throw new QueryException(
+                "Google API response issue: {$message}",
+                0
+            );
+        }
+
+        if (!isset($candidate[self::RESPONSE_KEY_CONTENT])) {
+            $responseJson = json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+            $responseStr = is_string($responseJson) ? substr($responseJson, 0, 500) : 'Unable to encode response';
+            throw new QueryException(
+                'Invalid response format from Google API: missing "content" key in candidate. Response: ' . $responseStr,
+                0
+            );
+        }
+
+        $content = $candidate[self::RESPONSE_KEY_CONTENT];
+
+        if (!isset($content[self::REQUEST_KEY_PARTS]) || empty($content[self::REQUEST_KEY_PARTS])) {
+            $responseJson = json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+            $responseStr = is_string($responseJson) ? substr($responseJson, 0, 500) : 'Unable to encode response';
+            throw new QueryException(
+                'Invalid response format from Google API: missing or empty "parts" array. Response: ' . $responseStr,
+                0
+            );
+        }
+
+        $part = $content[self::REQUEST_KEY_PARTS][0];
+
+        if (!isset($part[self::REQUEST_KEY_TEXT])) {
+            $responseJson = json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+            $responseStr = is_string($responseJson) ? substr($responseJson, 0, 500) : 'Unable to encode response';
+            throw new QueryException(
+                'Invalid response format from Google API: missing "text" key in part. Response: ' . $responseStr,
+                0
+            );
+        }
+
+        return (string)$part[self::REQUEST_KEY_TEXT];
     }
 
     protected function buildSystemPrompt(string $type): string