$performance * @return array * * @throws ConnectionException */ public function analyzeStudentPerformance(array $performance): array { $text = $this->generate(self::ANALYSIS_SCHEMA_HINT."\n\nبيانات الطالب:\n".json_encode($performance, JSON_UNESCAPED_UNICODE)); return $this->decodeJson($text); } /** * @param array $activity * @return array * * @throws ConnectionException */ public function generateParentWeeklyReport(array $activity): array { $prompt = <<<'PROMPT' أنت مستشار تعليمي. اكتب تقريراً أسبوعياً لولي أمر طالب توجيهي بناءً على البيانات التالية. أعد JSON فقط بهذا الشكل: {"headline": "...", "progress_note": "...", "weak_points": ["..."], "home_advice": ["..."]} استخدم العربية الواضحة دون مصطلحات تقنية. PROMPT; $text = $this->generate($prompt."\n\nبيانات النشاط:\n".json_encode($activity, JSON_UNESCAPED_UNICODE)); return $this->decodeJson($text); } /** * @throws ConnectionException */ private function generate(string $prompt): string { $config = config('services.gemini'); $model = is_array($config) ? ($config['model'] ?? 'gemini-2.5-flash-lite') : 'gemini-2.5-flash-lite'; $response = Http::withHeaders([ 'x-goog-api-key' => is_array($config) ? (string) $config['key'] : '', ]) ->timeout(is_array($config) ? (int) ($config['timeout'] ?? 30) : 30) ->retry(2, 500) ->post(rtrim((string) (is_array($config) ? $config['base_url'] : ''), '/')."/models/{$model}:generateContent", [ 'contents' => [ ['parts' => [['text' => $prompt]]], ], 'generationConfig' => [ 'temperature' => 0.4, 'responseMimeType' => 'application/json', ], ]); if ($response->failed()) { Log::warning('Gemini request failed', ['status' => $response->status(), 'body' => mb_substr($response->body(), 0, 500)]); throw new ConnectionException('Gemini API request failed.'); } /** @var array{candidates?: list}}> $payload */ $payload = $response->json(); return $payload['candidates'][0]['content']['parts'][0]['text'] ?? '{}'; } /** * @return array */ private function decodeJson(string $text): array { /** @var array $decoded */ $decoded = json_decode(trim($text), true); if (! is_array($decoded)) { throw new \RuntimeException('Gemini returned invalid JSON payload.'); } return $decoded; } }