Merge pull request #169 from acara-app/feature/telegram-photo-analysis

feat: add Telegram photo analysis and attachment support

Author: tuvshinjargal

.agents/skills/analyse-with-phpstan

@@ -0,0 +1 @@
+../../.ai/skills/analyse-with-phpstan

.ai/skills/analyse-with-phpstan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: analyse-with-phpstan
+description: Analyse PHP code with PHPStan via the playground API. Tests across all PHP versions (7.2–8.5) and reports errors grouped by version. Supports configuring level, strict rules, and bleeding edge.
+argument-hint: <php-code-or-file>
+disable-model-invocation: false
+---
+
+# Analyse PHP code with PHPStan
+
+Analyse PHP code using the PHPStan playground API at `https://api.phpstan.org/analyse`. This runs PHPStan across PHP versions 7.2–8.5 and returns errors for each version.
+
+The code to analyse: `$ARGUMENTS`
+
+## Step 1: Prepare the code
+
+Get the PHP code to analyse. If `$ARGUMENTS` is a file path, read the file contents. The code must start with `<?php`.
+
+## Step 2: Determine settings
+
+Unless the user specified otherwise, use these defaults:
+
+- **level**: `"10"` (strictest)
+- **strictRules**: `false`
+- **bleedingEdge**: `false`
+- **treatPhpDocTypesAsCertain**: `true`
+
+If the user asked for strict rules or bleeding edge, set those to `true`.
+
+## Step 3: Call the playground API
+
+Submit the code via POST:
+
+```bash
+curl -s -X POST 'https://api.phpstan.org/analyse' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "code": "<PHP code, JSON-escaped>",
+    "level": "<level>",
+    "strictRules": <true|false>,
+    "bleedingEdge": <true|false>,
+    "treatPhpDocTypesAsCertain": <true|false>,
+    "saveResult": true
+  }'
+```
+
+The code value must be properly JSON-escaped (escape quotes, backslashes, newlines).
+
+## Step 4: Parse the response
+
+The response JSON contains:
+
+- `versionedErrors` — array of objects, one per PHP version, each with:
+    - `phpVersion` — integer encoding: e.g. `80400` = PHP 8.4, `70400` = PHP 7.4
+    - `errors` — array of error objects with `message`, `line`, `identifier`, `tip` (optional), `ignorable`
+- `id` — UUID for the saved result
+
+Convert `phpVersion` integers to readable strings: `Math.floor(v / 10000)` `.` `Math.floor((v % 10000) / 100)`.
+
+## Step 5: Present results as markdown
+
+Output the results in this format:
+
+### Playground link
+
+`https://phpstan.org/r/<id>`
+
+### Settings used
+
+**Level:** `<level>` | **Strict rules:** yes/no | **Bleeding edge:** yes/no
+
+### Errors
+
+Group consecutive PHP versions that have identical errors (same messages, lines, and identifiers) into ranges. For example, if PHP 7.2–8.3 all report the same errors, show them as one group.
+
+If all PHP versions report identical errors, show a single group:
+
+**All PHP versions (no differences):**
+
+| Line | Error                                          | Identifier      |
+| ---- | ---------------------------------------------- | --------------- |
+| 10   | `Parameter #1 $foo expects string, int given.` | `argument.type` |
+
+If errors differ across versions, show separate groups:
+
+**PHP 8.0 – 8.5:**
+
+| Line | Error                                          | Identifier      |
+| ---- | ---------------------------------------------- | --------------- |
+| 10   | `Parameter #1 $foo expects string, int given.` | `argument.type` |

app/Actions/BuildAssistantAgentAction.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions;
+
+use App\Ai\Agents\AssistantAgent;
+use App\Http\Requests\StoreAgentConversationRequest;
+use App\Models\User;
+
+final class BuildAssistantAgentAction
+{
+    /**
+     * Resolve and fully configure an AssistantAgent for the given request and user.
+     *
+     * Responsibilities:
+     *  - Resolve the agent from the container
+     *  - Wire the agent mode and attachments from the request
+     *  - Conditionally enable web search based on the selected model
+     */
+    public function handle(StoreAgentConversationRequest $request, User $user): AssistantAgent
+    {
+        $model = $request->modelName();
+        $attachments = $request->userAttachments();
+
+        $agent = resolve(AssistantAgent::class, ['user' => $user])
+            ->withMode($request->mode())
+            ->withAttachments($attachments)
+            ->forUser($user);
+
+        if ($model->supportsWebSearch()) {
+            $agent->withWebSearch();
+        }
+
+        return $agent;
+    }
+}

app/Actions/BuildConversationMessagesAction.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions;
+
+use App\Models\Conversation;
+use App\Models\History;
+
+final class BuildConversationMessagesAction
+{
+    /**
+     * Build the AI SDK message array from a Conversation's History records.
+     *
+     * Returns an empty array when no conversation is provided.
+     *
+     * @return list<array{id: string, role: string, parts: list<array<string, string>>}>
+     */
+    public function handle(?Conversation $conversation): array
+    {
+        if (! $conversation instanceof Conversation) {
+            return [];
+        }
+
+        return $conversation->messages
+            ->map(fn (History $message): array => [
+                'id' => $message->id,
+                'role' => $message->role->value,
+                'parts' => $this->buildParts($message),
+            ])
+            ->all();
+    }
+
+    /**
+     * Build the parts array for a single history message.
+     *
+     * Always starts with a text part, then appends one part per attachment.
+     *
+     * @return list<array<string, string>>
+     */
+    private function buildParts(History $message): array
+    {
+        $textPart = ['type' => 'text', 'text' => $message->content];
+
+        $attachmentParts = collect($message->attachments ?? [])
+            ->map(function (array $attachment): array { // @phpstan-ignore-line argument.type
+                $mime = isset($attachment['mime']) && is_string($attachment['mime'])
+                    ? $attachment['mime']
+                    : 'image/jpeg';
+
+                $base64 = isset($attachment['base64']) && is_string($attachment['base64'])
+                    ? $attachment['base64']
+                    : '';
+
+                return [
+                    'type' => 'file',
+                    'mediaType' => $mime,
+                    'url' => 'data:'.$mime.';base64,'.$base64,
+                ];
+            })
+            ->all();
+
+        return [$textPart, ...$attachmentParts];
+    }
+}

app/Actions/DownloadTelegramPhotoAction.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions;
+
+use App\Contracts\DownloadsTelegramPhoto;
+use DefStudio\Telegraph\DTO\Photo;
+use DefStudio\Telegraph\Models\TelegraphBot;
+use Illuminate\Support\Facades\Http;
+use Laravel\Ai\Files\Base64Image;
+use RuntimeException;
+
+final readonly class DownloadTelegramPhotoAction implements DownloadsTelegramPhoto
+{
+    public function handle(TelegraphBot $bot, Photo $photo): Base64Image
+    {
+        $telegraph = $bot->getFileInfo($photo->id());
+        $response = $telegraph->send();
+
+        if ($response->telegraphError()) {
+            throw new RuntimeException('Failed to retrieve file info for Telegram photo: '.$photo->id());
+        }
+
+        /** @var string $filePath */
+        $filePath = $response->json('result.file_path');
+
+        $fileResponse = Http::timeout(30)->get($telegraph->getFilesUrl().'/'.$filePath);
+
+        if ($fileResponse->failed()) {
+            throw new RuntimeException('Failed to download Telegram photo: '.$photo->id());
+        }
+
+        return new Base64Image(
+            base64_encode($fileResponse->body()),
+            $this->resolveMimeType($filePath, $fileResponse->header('Content-Type')),
+        );
+    }
+
+    private function resolveMimeType(string $filePath, ?string $contentType): string
+    {
+        if ($contentType !== null && str_starts_with($contentType, 'image/')) {
+            return $contentType;
+        }
+
+        return match (pathinfo($filePath, PATHINFO_EXTENSION)) {
+            'png' => 'image/png',
+            'gif' => 'image/gif',
+            'webp' => 'image/webp',
+            default => 'image/jpeg',
+        };
+    }
+}

app/Actions/ProcessAdvisorMessageAction.php

@@ -9,6 +9,7 @@
 use App\Models\User;
 use Illuminate\Support\Facades\Auth;
 use Laravel\Ai\Contracts\ConversationStore;
+use Laravel\Ai\Files\Base64Image;
 
 final readonly class ProcessAdvisorMessageAction implements ProcessesAdvisorMessage
 {
@@ -18,9 +19,10 @@ public function __construct(
     ) {}
 
     /**
+     * @param  array<int, Base64Image>  $attachments
      * @return array{response: string, conversation_id: string}
      */
-    public function handle(User $user, string $message, ?string $conversationId = null): array
+    public function handle(User $user, string $message, ?string $conversationId = null, array $attachments = []): array
     {
         // Ensure the user is set in the auth guard so AI tools can access it
         // via Auth::user() (Telegram requests bypass web auth middleware).
@@ -29,8 +31,11 @@ public function handle(User $user, string $message, ?string $conversationId = nu
         $conversationId ??= $this->conversationStore->latestConversationId($user->id)
             ?? $this->conversationStore->storeConversation($user->id, 'Telegram Chat');
 
-        $agent = $this->advisor->continue($conversationId, $user);
-        $response = $agent->prompt($message);
+        $agent = $this->advisor
+            ->withAttachments($attachments)
+            ->continue($conversationId, $user);
+
+        $response = $agent->prompt($message, attachments: $attachments);
 
         return [
             'response' => $response->text,

app/Ai/Agents/AssistantAgent.php

@@ -6,6 +6,7 @@
 
 use App\Actions\GetUserProfileContextAction;
 use App\Ai\SystemPrompt;
+use App\Ai\Tools\AnalyzePhoto;
 use App\Ai\Tools\CreateMealPlan;
 use App\Ai\Tools\GetDietReference;
 use App\Ai\Tools\GetFitnessGoals;
@@ -20,20 +21,31 @@
 use App\Enums\AgentMode;
 use App\Models\User;
 use App\Utilities\LanguageUtil;
+use Laravel\Ai\Attributes\Timeout;
 use Laravel\Ai\Concerns\RemembersConversations;
 use Laravel\Ai\Contracts\Agent;
 use Laravel\Ai\Contracts\Conversational;
 use Laravel\Ai\Contracts\HasTools;
 use Laravel\Ai\Contracts\Tool;
+use Laravel\Ai\Files\Base64Image;
 use Laravel\Ai\Promptable;
 use Laravel\Ai\Providers\Tools\ProviderTool;
+use Laravel\Ai\Providers\Tools\WebSearch;
 
+#[Timeout(120)]
 final class AssistantAgent implements Agent, Conversational, HasTools
 {
     use Promptable, RemembersConversations;
 
     private AgentMode $mode = AgentMode::Ask;
 
+    /**
+     * @var array<int, Base64Image>
+     */
+    private array $attachments = [];
+
+    private bool $webSearchEnabled = false;
+
     /**
      * @var array<int, Tool|ProviderTool>
      */
@@ -51,6 +63,23 @@ public function addTool(Tool|ProviderTool $tool): self
         return $this;
     }
 
+    /**
+     * @param  array<int, Base64Image>  $attachments
+     */
+    public function withAttachments(array $attachments): self
+    {
+        $this->attachments = $attachments;
+
+        return $this;
+    }
+
+    public function withWebSearch(): self
+    {
+        $this->webSearchEnabled = true;
+
+        return $this;
+    }
+
     public function withMode(AgentMode $mode): self
     {
         $this->mode = $mode;
@@ -60,7 +89,8 @@ public function withMode(AgentMode $mode): self
 
     public function instructions(): string
     {
-        $user = $this->conversationUser instanceof User ? $this->conversationUser : $this->user;
+        $participant = $this->conversationParticipant();
+        $user = $participant instanceof User ? $participant : $this->user;
         $profileData = $this->profileContext->handle($user);
 
         return (string) new SystemPrompt(
@@ -77,7 +107,7 @@ public function instructions(): string
      */
     public function tools(): array
     {
-        return array_merge([
+        $tools = [
             new SuggestSingleMeal,
             new GetUserProfile,
             new CreateMealPlan,
@@ -89,7 +119,17 @@ public function tools(): array
             new SuggestWorkoutRoutine,
             new GetFitnessGoals,
             new GetDietReference,
-        ], $this->additionalTools);
+        ];
+
+        if ($this->attachments !== []) {
+            $tools[] = new AnalyzePhoto($this->attachments);
+        }
+
+        if ($this->webSearchEnabled) {
+            $tools[] = new WebSearch;
+        }
+
+        return array_merge($tools, $this->additionalTools);
     }
 
     /**