feat: Add response metadata fields

src/Data/Candidate.php

@@ -27,6 +27,8 @@ final class Candidate implements Arrayable
      * @param  GroundingMetadata|null  $groundingMetadata  Output only. Grounding metadata for the candidate. This field is populated for GenerateContent calls.
      * @param  LogprobsResult|null  $logprobsResult  Output only. Log-likelihood scores for the response tokens and top tokens.
      * @param  UrlRetrievalMetadata|null  $urlRetrievalMetadata  Output only. Metadata related to url context retrieval tool.
+     * @param  string|null  $finishMessage  Optional. Output only. Details the reason why the model stopped generating tokens. This is populated only when `finishReason` is set.
+     * @param  UrlContextMetadata|null  $urlContextMetadata  Output only. Metadata related to url context retrieval tool.
      */
     public function __construct(
         public readonly Content $content,
@@ -40,10 +42,12 @@ public function __construct(
         public readonly ?GroundingMetadata $groundingMetadata = null,
         public readonly ?LogprobsResult $logprobsResult = null,
         public readonly ?UrlRetrievalMetadata $urlRetrievalMetadata = null,
+        public readonly ?string $finishMessage = null,
+        public readonly ?UrlContextMetadata $urlContextMetadata = null,
     ) {}
 
     /**
-     * @param  array{ content: ?array{ parts: array{ array{ text: ?string, inlineData: ?array{ mimeType: string, data: string }, fileData: ?array{ fileUri: string, mimeType: string }, functionCall: ?array{ name: string, args: array<string, mixed>|null }, functionResponse: ?array{ name: string, response: array<string, mixed> } } }, role: string }, finishReason: ?string, safetyRatings: ?array{ array{ category: string, probability: string, blocked: ?bool } }, citationMetadata: ?array{ citationSources: array{ array{ startIndex: int, endIndex: int, uri: ?string, license: ?string} } }, index: ?int, tokenCount: ?int, avgLogprobs: ?float, groundingAttributions: ?array<array{ sourceId: array{ groundingPassage?: array{ passageId: string, partIndex: int }, semanticRetrieverChunk?: array{ source: string, chunk: string } }, content: array{ parts: array{ array{ text: ?string, inlineData: ?array{ mimeType: string, data: string }, fileData: ?array{ fileUri: string, mimeType: string }, functionCall: ?array{ name: string, args: array<string, mixed>|null }, functionResponse: ?array{ name: string, response: array<string, mixed> } } }, role: string } }>, groundingMetadata?: array{ groundingChunks: ?array<array{ web: null|array{ title: ?string, uri: ?string }, retrievedContext: null|array{ uri: ?string, title: ?string, text: ?string, fileSearchStore: ?string }, maps: null|array{ uri: ?string, title: ?string, text: ?string, placeId: ?string, placeAnswerSources: ?array{ reviewSnippets: array<array{title: ?string, googleMapsUri: ?string, reviewId: ?string}> } } }>, groundingSupports: ?array<array{ groundingChunkIndices: array<int>|null, confidenceScores: array<float>|null, segment: ?array{ partIndex: ?int, startIndex: ?int, endIndex: ?int, text: ?string } }>, webSearchQueries: ?array<string>, searchEntryPoint?: array{ renderedContent?: string|null, sdkBlob?: string|null }, retrievalMetadata: ?array{ googleSearchDynamicRetrievalScore?: float|null } }, logprobsResult?: array{ topCandidates: array<array{ candidates: array<array{ token: string, tokenId: int, logProbability: float }> }>, chosenCandidates: array<array{ token: string, tokenId: int, logProbability: float }> }, urlRetrievalMetadata?: array{ urlRetrievalContexts: array<array{ retrievedUrl: string }> } }  $attributes
+     * @param  array{ content: ?array{ parts: array{ array{ text: ?string, inlineData: ?array{ mimeType: string, data: string }, fileData: ?array{ fileUri: string, mimeType: string }, functionCall: ?array{ name: string, args: array<string, mixed>|null }, functionResponse: ?array{ name: string, response: array<string, mixed> } } }, role: string }, finishReason: ?string, safetyRatings: ?array{ array{ category: string, probability: string, blocked: ?bool } }, citationMetadata: ?array{ citationSources: array{ array{ startIndex: int, endIndex: int, uri: ?string, license: ?string} } }, index: ?int, tokenCount: ?int, avgLogprobs: ?float, groundingAttributions: ?array<array{ sourceId: array{ groundingPassage?: array{ passageId: string, partIndex: int }, semanticRetrieverChunk?: array{ source: string, chunk: string } }, content: array{ parts: array{ array{ text: ?string, inlineData: ?array{ mimeType: string, data: string }, fileData: ?array{ fileUri: string, mimeType: string }, functionCall: ?array{ name: string, args: array<string, mixed>|null }, functionResponse: ?array{ name: string, response: array<string, mixed> } } }, role: string } }>, groundingMetadata?: array{ groundingChunks: ?array<array{ web: null|array{ title: ?string, uri: ?string }, retrievedContext: null|array{ uri: ?string, title: ?string, text: ?string, fileSearchStore: ?string }, maps: null|array{ uri: ?string, title: ?string, text: ?string, placeId: ?string, placeAnswerSources: ?array{ reviewSnippets: array<array{title: ?string, googleMapsUri: ?string, reviewId: ?string}> } } }>, groundingSupports: ?array<array{ groundingChunkIndices: array<int>|null, confidenceScores: array<float>|null, segment: ?array{ partIndex: ?int, startIndex: ?int, endIndex: ?int, text: ?string } }>, webSearchQueries: ?array<string>, searchEntryPoint?: array{ renderedContent?: string|null, sdkBlob?: string|null }, retrievalMetadata: ?array{ googleSearchDynamicRetrievalScore?: float|null } }, logprobsResult?: array{ topCandidates: array<array{ candidates: array<array{ token: string, tokenId: int, logProbability: float }> }>, chosenCandidates: array<array{ token: string, tokenId: int, logProbability: float }> }, urlRetrievalMetadata?: array{ urlRetrievalContexts: array<array{ retrievedUrl: string }> }, finishMessage?: string, urlContextMetadata?: array{ urlMetadata?: array<array{ retrievedUrl?: string, urlRetrievalStatus?: string }> } }  $attributes
      */
     public static function from(array $attributes): self
     {
@@ -69,6 +73,8 @@ public static function from(array $attributes): self
             groundingMetadata: isset($attributes['groundingMetadata']) ? GroundingMetadata::from($attributes['groundingMetadata']) : null,
             logprobsResult: isset($attributes['logprobsResult']) ? LogprobsResult::from($attributes['logprobsResult']) : null,
             urlRetrievalMetadata: isset($attributes['urlRetrievalMetadata']) ? UrlRetrievalMetadata::from($attributes['urlRetrievalMetadata']) : null,
+            finishMessage: $attributes['finishMessage'] ?? null,
+            urlContextMetadata: isset($attributes['urlContextMetadata']) ? UrlContextMetadata::from($attributes['urlContextMetadata']) : null,
         );
     }
 
@@ -92,6 +98,8 @@ public function toArray(): array
             'groundingMetadata' => $this->groundingMetadata?->toArray(),
             'logprobsResult' => $this->logprobsResult?->toArray(),
             'urlRetrievalMetadata' => $this->urlRetrievalMetadata?->toArray(),
+            'finishMessage' => $this->finishMessage,
+            'urlContextMetadata' => $this->urlContextMetadata?->toArray(),
         ];
     }
 }

src/Data/ModelStatus.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Data;
+
+use Gemini\Contracts\Arrayable;
+use Gemini\Enums\ModelStage;
+
+/**
+ * The status of the underlying model. This is used to indicate the stage of the underlying model and the retirement time if applicable.
+ *
+ * https://ai.google.dev/api/generate-content#ModelStatus
+ */
+final class ModelStatus implements Arrayable
+{
+    /**
+     * @param  ModelStage|null  $modelStage  The stage of the underlying model.
+     * @param  string|null  $retirementTime  The time at which the model will be retired.
+     * @param  string|null  $message  A message explaining the model status.
+     */
+    public function __construct(
+        public readonly ?ModelStage $modelStage = null,
+        public readonly ?string $retirementTime = null,
+        public readonly ?string $message = null,
+    ) {}
+
+    /**
+     * @param  array{ modelStage?: string, retirementTime?: string, message?: string }  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            modelStage: isset($attributes['modelStage']) ? ModelStage::tryFrom($attributes['modelStage']) : null,
+            retirementTime: $attributes['retirementTime'] ?? null,
+            message: $attributes['message'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'modelStage' => $this->modelStage?->value,
+            'retirementTime' => $this->retirementTime,
+            'message' => $this->message,
+        ];
+    }
+}

src/Data/UrlContextMetadata.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Data;
+
+use Gemini\Contracts\Arrayable;
+
+/**
+ * Metadata related to url context retrieval tool.
+ *
+ * https://ai.google.dev/api/generate-content#UrlContextMetadata
+ */
+final class UrlContextMetadata implements Arrayable
+{
+    /**
+     * @param  array<UrlMetadata>  $urlMetadata  List of url context.
+     */
+    public function __construct(
+        public readonly array $urlMetadata = [],
+    ) {}
+
+    /**
+     * @param  array{ urlMetadata?: array<array{ retrievedUrl?: string, urlRetrievalStatus?: string }> }  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            urlMetadata: array_map(
+                static fn (array $urlMetadata): UrlMetadata => UrlMetadata::from($urlMetadata),
+                $attributes['urlMetadata'] ?? [],
+            ),
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'urlMetadata' => array_map(
+                static fn (UrlMetadata $urlMetadata): array => $urlMetadata->toArray(),
+                $this->urlMetadata,
+            ),
+        ];
+    }
+}

src/Data/UrlMetadata.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Data;
+
+use Gemini\Contracts\Arrayable;
+use Gemini\Enums\UrlRetrievalStatus;
+
+/**
+ * Context of a single url retrieval.
+ *
+ * https://ai.google.dev/api/generate-content#UrlMetadata
+ */
+final class UrlMetadata implements Arrayable
+{
+    /**
+     * @param  string|null  $retrievedUrl  Retrieved url by the tool.
+     * @param  UrlRetrievalStatus|null  $urlRetrievalStatus  Status of the url retrieval.
+     */
+    public function __construct(
+        public readonly ?string $retrievedUrl = null,
+        public readonly ?UrlRetrievalStatus $urlRetrievalStatus = null,
+    ) {}
+
+    /**
+     * @param  array{ retrievedUrl?: string, urlRetrievalStatus?: string }  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            retrievedUrl: $attributes['retrievedUrl'] ?? null,
+            urlRetrievalStatus: isset($attributes['urlRetrievalStatus']) ? UrlRetrievalStatus::tryFrom($attributes['urlRetrievalStatus']) : null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'retrievedUrl' => $this->retrievedUrl,
+            'urlRetrievalStatus' => $this->urlRetrievalStatus?->value,
+        ];
+    }
+}

src/Data/UsageMetadata.php

@@ -5,6 +5,7 @@
 namespace Gemini\Data;
 
 use Gemini\Contracts\Arrayable;
+use Gemini\Enums\ServiceTier;
 
 /**
  * Metadata on the generation request's token usage.
@@ -24,6 +25,7 @@ final class UsageMetadata implements Arrayable
      * @param  list<ModalityTokenCount>|null  $cacheTokensDetails  List of modalities of the cached content in the request input.
      * @param  list<ModalityTokenCount>|null  $candidatesTokensDetails  List of modalities that were returned in the response.
      * @param  list<ModalityTokenCount>|null  $toolUsePromptTokensDetails  List of modalities that were processed for tool-use request inputs.
+     * @param  ServiceTier|null  $serviceTier  Output only. Service tier of the request.
      */
     public function __construct(
         public readonly int $promptTokenCount,
@@ -36,10 +38,11 @@ public function __construct(
         public readonly ?array $cacheTokensDetails = null,
         public readonly ?array $candidatesTokensDetails = null,
         public readonly ?array $toolUsePromptTokensDetails = null,
+        public readonly ?ServiceTier $serviceTier = null,
     ) {}
 
     /**
-     * @param  array{ promptTokenCount?: int, totalTokenCount: int, candidatesTokenCount: ?int, cachedContentTokenCount: ?int, toolUsePromptTokenCount: ?int, thoughtsTokenCount: ?int, promptTokensDetails: list<array{ modality: string, tokenCount: int}>|null, cacheTokensDetails: list<array{ modality: string, tokenCount: int}>|null, candidatesTokensDetails: list<array{ modality: string, tokenCount: int}>|null, toolUsePromptTokensDetails: list<array{ modality: string, tokenCount: int}>|null }  $attributes
+     * @param  array{ promptTokenCount?: int, totalTokenCount: int, candidatesTokenCount: ?int, cachedContentTokenCount: ?int, toolUsePromptTokenCount: ?int, thoughtsTokenCount: ?int, promptTokensDetails: list<array{ modality: string, tokenCount: int}>|null, cacheTokensDetails: list<array{ modality: string, tokenCount: int}>|null, candidatesTokensDetails: list<array{ modality: string, tokenCount: int}>|null, toolUsePromptTokensDetails: list<array{ modality: string, tokenCount: int}>|null, serviceTier?: string }  $attributes
      */
     public static function from(array $attributes): self
     {
@@ -67,6 +70,7 @@ public static function from(array $attributes): self
                 static fn (array $toolUsePromptTokensDetail): ModalityTokenCount => ModalityTokenCount::from($toolUsePromptTokensDetail),
                 $attributes['toolUsePromptTokensDetails'] ?? [],
             ),
+            serviceTier: isset($attributes['serviceTier']) ? ServiceTier::tryFrom($attributes['serviceTier']) : null,
         );
     }
 
@@ -95,6 +99,7 @@ public function toArray(): array
                 static fn (ModalityTokenCount $toolUsePromptTokensDetail): array => $toolUsePromptTokensDetail->toArray(),
                 $this->toolUsePromptTokensDetails ?? [],
             ),
+            'serviceTier' => $this->serviceTier?->value,
         ];
     }
 }

src/Enums/ModelStage.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Enums;
+
+/**
+ * The stage of the underlying model.
+ *
+ * https://ai.google.dev/api/generate-content#ModelStage
+ */
+enum ModelStage: string
+{
+    /**
+     * Unspecified model stage.
+     */
+    case MODEL_STAGE_UNSPECIFIED = 'MODEL_STAGE_UNSPECIFIED';
+
+    /**
+     * The underlying model is subject to lots of tunings.
+     */
+    case UNSTABLE_EXPERIMENTAL = 'UNSTABLE_EXPERIMENTAL';
+
+    /**
+     * Models in this stage are for experimental purposes only.
+     */
+    case EXPERIMENTAL = 'EXPERIMENTAL';
+
+    /**
+     * Models in this stage are more mature than experimental models.
+     */
+    case PREVIEW = 'PREVIEW';
+
+    /**
+     * Models in this stage are considered stable and ready for production use.
+     */
+    case STABLE = 'STABLE';
+
+    /**
+     * The model is on the path to deprecation in near future. Only existing customers can use this model.
+     */
+    case LEGACY = 'LEGACY';
+
+    /**
+     * Models in this stage are deprecated. These models cannot be used.
+     */
+    case DEPRECATED = 'DEPRECATED';
+
+    /**
+     * Models in this stage are retired. These models cannot be used.
+     */
+    case RETIRED = 'RETIRED';
+}

src/Enums/ServiceTier.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Enums;
+
+/**
+ * Service tier of the request.
+ *
+ * https://ai.google.dev/api/generate-content#ServiceTier
+ */
+enum ServiceTier: string
+{
+    /**
+     * Default service tier, which is standard.
+     */
+    case UNSPECIFIED = 'unspecified';
+
+    /**
+     * Standard service tier.
+     */
+    case STANDARD = 'standard';
+
+    /**
+     * Flex service tier.
+     */
+    case FLEX = 'flex';
+
+    /**
+     * Priority service tier.
+     */
+    case PRIORITY = 'priority';
+}

src/Enums/UrlRetrievalStatus.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gemini\Enums;
+
+/**
+ * Status of the url retrieval.
+ *
+ * https://ai.google.dev/api/generate-content#UrlRetrievalStatus
+ */
+enum UrlRetrievalStatus: string
+{
+    /**
+     * Default value. This value is unused.
+     */
+    case URL_RETRIEVAL_STATUS_UNSPECIFIED = 'URL_RETRIEVAL_STATUS_UNSPECIFIED';
+
+    /**
+     * Url retrieval is successful.
+     */
+    case URL_RETRIEVAL_STATUS_SUCCESS = 'URL_RETRIEVAL_STATUS_SUCCESS';
+
+    /**
+     * Url retrieval is failed due to error.
+     */
+    case URL_RETRIEVAL_STATUS_ERROR = 'URL_RETRIEVAL_STATUS_ERROR';
+
+    /**
+     * Url retrieval is failed because the content is behind paywall.
+     */
+    case URL_RETRIEVAL_STATUS_PAYWALL = 'URL_RETRIEVAL_STATUS_PAYWALL';
+
+    /**
+     * Url retrieval is failed because the content is unsafe.
+     */
+    case URL_RETRIEVAL_STATUS_UNSAFE = 'URL_RETRIEVAL_STATUS_UNSAFE';
+}