feature #720 [Agent][Platform] Improve ResultConverterPHPDoc (VincentLanglet)

This PR was merged into the main branch.

Discussion
----------

[Agent][Platform] Improve `ResultConverter`PHPDoc

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | yes
| Issues        | Fix #...
| License       | MIT

Since #538 exceptions thrown by `ResultConverterInterface::convert` are more useful and should be documented.
I personally use them when doing `Agent::call`, and they are accessible because
Agent::call use `getResult` which use `await` which use `convert`.

I added some basic documentation about them then.

Commits
-------

10ce6b3 Improve ResultConverter phpdoc

Author: OskarStark

src/agent/src/Agent.php

@@ -17,6 +17,7 @@
 use Symfony\AI\Agent\Exception\MissingModelSupportException;
 use Symfony\AI\Agent\Exception\RuntimeException;
 use Symfony\AI\Platform\Capability;
+use Symfony\AI\Platform\Exception\ExceptionInterface;
 use Symfony\AI\Platform\Message\MessageBag;
 use Symfony\AI\Platform\Model;
 use Symfony\AI\Platform\PlatformInterface;
@@ -72,6 +73,7 @@ public function getName(): string
      * @throws MissingModelSupportException When the model doesn't support audio or image inputs present in the messages
      * @throws InvalidArgumentException     When the platform returns a client error (4xx) indicating invalid request parameters
      * @throws RuntimeException             When the platform returns a server error (5xx) or network failure occurs
+     * @throws ExceptionInterface           When the platform converter throws an exception
      */
     public function call(MessageBag $messages, array $options = []): ResultInterface
     {

src/platform/src/Result/ResultPromise.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\AI\Platform\Result;
 
+use Symfony\AI\Platform\Exception\ExceptionInterface;
 use Symfony\AI\Platform\Exception\UnexpectedResultTypeException;
 use Symfony\AI\Platform\Vector\Vector;
 
@@ -32,6 +33,9 @@ public function __construct(
     ) {
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function getResult(): ResultInterface
     {
         return $this->await();
@@ -42,6 +46,9 @@ public function getRawResult(): RawResultInterface
         return $this->rawResult;
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function await(): ResultInterface
     {
         if (!$this->isConverted) {
@@ -58,21 +65,33 @@ public function await(): ResultInterface
         return $this->convertedResult;
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function asText(): string
     {
         return $this->as(TextResult::class)->getContent();
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function asObject(): object
     {
         return $this->as(ObjectResult::class)->getContent();
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function asBinary(): string
     {
         return $this->as(BinaryResult::class)->getContent();
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function asBase64(): string
     {
         $result = $this->as(BinaryResult::class);
@@ -84,19 +103,26 @@ public function asBase64(): string
 
     /**
      * @return Vector[]
+     *
+     * @throws ExceptionInterface
      */
     public function asVectors(): array
     {
         return $this->as(VectorResult::class)->getContent();
     }
 
+    /**
+     * @throws ExceptionInterface
+     */
     public function asStream(): \Generator
     {
         yield from $this->as(StreamResult::class)->getContent();
     }
 
     /**
      * @return ToolCall[]
+     *
+     * @throws ExceptionInterface
      */
     public function asToolCalls(): array
     {
@@ -105,6 +131,8 @@ public function asToolCalls(): array
 
     /**
      * @param class-string $type
+     *
+     * @throws ExceptionInterface
      */
     private function as(string $type): ResultInterface
     {

src/platform/src/ResultConverterInterface.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\AI\Platform;
 
+use Symfony\AI\Platform\Exception\ExceptionInterface;
 use Symfony\AI\Platform\Result\RawResultInterface;
 use Symfony\AI\Platform\Result\ResultInterface;
 
@@ -23,6 +24,8 @@ public function supports(Model $model): bool;
 
     /**
      * @param array<string, mixed> $options
+     *
+     * @throws ExceptionInterface
      */
     public function convert(RawResultInterface $result, array $options = []): ResultInterface;
 }