Add streaming response generation

Closes #21

Author: erdemkose

README.md

@@ -22,6 +22,7 @@ _This library is not developed or endorsed by Google._
  - [Multimodal input](#multimodal-input)
  - [Chat Session (Multi-Turn Conversations)](#chat-session-multi-turn-conversations)
  - [Chat Session with history](#chat-session-with-history)
+ - [Streaming responses](#streaming-responses)
  - [Tokens counting](#tokens-counting)
  - [Listing models](#listing-models)
 
@@ -150,6 +151,34 @@ func main() {
 This code will print "Hello World!" to the standard output.
 ```
 
+### Streaming responses
+
+In the streaming response, the callback function will be called whenever a response is returned from the server.
+
+Long responses may be broken into separate responses, and you can start receiving responses faster using a content stream.
+
+```php
+$client = new GeminiAPI\Client('GEMINI_API_KEY');
+
+$callback = function (GenerateContentResponse $response): void {
+ static $count = 0;
+
+ print "\nResponse #{$count}\n";
+ print $response->text();
+ $count++;
+};
+
+$client->geminiPro()->generateContentStream(
+ $callback,
+ new TextPart('PHP in less than 100 chars')
+);
+// Response #0
+// PHP: a versatile, general-purpose scripting language for web development, popular for
+// Response #1
+// its simple syntax and rich library of functions.
+```
+
+
 ### Embed Content
 
 ```php

composer.json

@@ -35,6 +35,9 @@
  "phpstan/phpstan": "^1.10.50",
  "phpunit/phpunit": "^10.5"
  },
+ "suggest": {
+ "ext-curl": "Required for streaming responses"
+ },
  "autoload": {
  "psr-4": {
  "GeminiAPI\\": "src/"

src/Client.php

@@ -4,11 +4,15 @@
 
 namespace GeminiAPI;
 
+use BadMethodCallException;
+use CurlHandle;
 use GeminiAPI\ClientInterface as GeminiClientInterface;
 use GeminiAPI\Enums\ModelName;
+use GeminiAPI\Json\ObjectListParser;
 use GeminiAPI\Requests\CountTokensRequest;
 use GeminiAPI\Requests\EmbedContentRequest;
 use GeminiAPI\Requests\GenerateContentRequest;
+use GeminiAPI\Requests\GenerateContentStreamRequest;
 use GeminiAPI\Requests\ListModelsRequest;
 use GeminiAPI\Requests\RequestInterface;
 use GeminiAPI\Responses\CountTokensResponse;
@@ -23,6 +27,11 @@
 use Psr\Http\Message\StreamFactoryInterface;
 use RuntimeException;
 
+use function curl_close;
+use function curl_exec;
+use function curl_init;
+use function curl_setopt;
+use function extension_loaded;
 use function json_decode;
 
 class Client implements GeminiClientInterface
@@ -76,6 +85,38 @@ public function generateContent(GenerateContentRequest $request): GenerateConten
  return GenerateContentResponse::fromArray($json);
  }
 
+ /**
+ * @param callable(GenerateContentResponse): void $callback
+ * @throws BadMethodCallException
+ * @throws RuntimeException
+ */
+ public function generateContentStream(
+ GenerateContentStreamRequest $request,
+ callable $callback,
+ ): void {
+ if (!extension_loaded('curl')) {
+ throw new BadMethodCallException('Gemini API requires `curl` extension for streaming responses');
+ }
+
+ $parser = new ObjectListParser(
+ /* @phpstan-ignore-next-line */
+ static fn (array $arr) => $callback(GenerateContentResponse::fromArray($arr)),
+ );
+
+ $ch = curl_init("{$this->baseUrl}/v1/{$request->getOperation()}");
+ curl_setopt($ch, CURLOPT_POST, true);
+ curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
+ curl_setopt($ch, CURLOPT_HTTPHEADER, [
+ 'Content-type: application/json',
+ self::API_KEY_HEADER_NAME . ": {$this->apiKey}",
+ ]);
+ curl_setopt($ch, CURLOPT_WRITEFUNCTION,
+ static fn (CurlHandle $ch, string $str): int => $parser->consume($str),
+ );
+ curl_exec($ch);
+ curl_close($ch);
+ }
+
  /**
  * @throws ClientExceptionInterface
  */

src/GenerativeModel.php

@@ -4,10 +4,12 @@
 
 namespace GeminiAPI;
 
+use BadMethodCallException;
 use GeminiAPI\Enums\ModelName;
 use GeminiAPI\Enums\Role;
 use GeminiAPI\Requests\CountTokensRequest;
 use GeminiAPI\Requests\GenerateContentRequest;
+use GeminiAPI\Requests\GenerateContentStreamRequest;
 use GeminiAPI\Responses\CountTokensResponse;
 use GeminiAPI\Responses\GenerateContentResponse;
 use GeminiAPI\Resources\Content;
@@ -58,6 +60,28 @@ public function generateContentWithContents(array $contents): GenerateContentRes
  return $this->client->generateContent($request);
  }
 
+ /**
+ * @param callable(GenerateContentResponse): void $callback
+ * @param PartInterface ...$parts
+ * @return void
+ * @throws BadMethodCallException
+ */
+ public function generateContentStream(
+ callable $callback,
+ PartInterface ...$parts,
+ ): void {
+ $content = new Content($parts, Role::User);
+
+ $request = new GenerateContentStreamRequest(
+ $this->modelName,
+ [$content],
+ $this->safetySettings,
+ $this->generationConfig,
+ );
+
+ $this->client->generateContentStream($request, $callback);
+ }
+
  public function startChat(): ChatSession
  {
  return new ChatSession($this);

src/Json/ObjectListParser.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GeminiAPI\Json;
+
+use RuntimeException;
+
+class ObjectListParser
+{
+ private int $depth = 0;
+ private bool $inString = false;
+ private bool $inEscape = false;
+ private string $json = '';
+
+ /** @var callable(array): void */
+ private $callback; // @phpstan-ignore-line
+
+ /**
+ * @phpstan-ignore-next-line
+ * @param callable(array): void $callback
+ */
+ public function __construct(callable $callback) {
+ $this->callback = $callback;
+ }
+
+ /**
+ * @param string $str
+ * @return int
+ * @throws RuntimeException
+ */
+ public function consume(string $str): int
+ {
+ $offset = 0;
+ for ($i = 0; $i < strlen($str); $i++) {
+ if ($this->inEscape) {
+ $this->inEscape = false;
+ } elseif ($this->inString) {
+ if ($str[$i] === '\\') {
+ $this->inEscape = true;
+ } elseif ($str[$i] === '"') {
+ $this->inString = false;
+ }
+ } elseif ($str[$i] === '"') {
+ $this->inString = true;
+ } elseif ($str[$i] === '{') {
+ if ($this->depth === 0) {
+ $offset = $i;
+ }
+ $this->depth++;
+ } elseif ($str[$i] === '}') {
+ $this->depth--;
+ if ($this->depth === 0) {
+ $this->json .= substr($str, $offset, $i - $offset + 1);
+ $arr = json_decode($this->json, true);
+
+ if (json_last_error() !== JSON_ERROR_NONE) {
+ throw new RuntimeException('ObjectListParser could not decode the given message');
+ }
+
+ ($this->callback)($arr);
+ $this->json = '';
+ $offset = $i + 1;
+ }
+ }
+ }
+
+ $this->json .= substr($str, $offset) ?: '';
+
+ return strlen($str);
+ }
+}

src/Requests/GenerateContentStreamRequest.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GeminiAPI\Requests;
+
+use GeminiAPI\Enums\ModelName;
+use GeminiAPI\GenerationConfig;
+use GeminiAPI\SafetySetting;
+use GeminiAPI\Traits\ArrayTypeValidator;
+use GeminiAPI\Resources\Content;
+use JsonSerializable;
+
+use function json_encode;
+
+class GenerateContentStreamRequest implements JsonSerializable, RequestInterface
+{
+ use ArrayTypeValidator;
+
+ /**
+ * @param ModelName $modelName
+ * @param Content[] $contents
+ * @param SafetySetting[] $safetySettings
+ * @param GenerationConfig|null $generationConfig
+ */
+ public function __construct(
+ public readonly ModelName $modelName,
+ public readonly array $contents,
+ public readonly array $safetySettings = [],
+ public readonly ?GenerationConfig $generationConfig = null,
+ ) {
+ $this->ensureArrayOfType($this->contents, Content::class);
+ $this->ensureArrayOfType($this->safetySettings, SafetySetting::class);
+ }
+
+ public function getOperation(): string
+ {
+ return "{$this->modelName->value}:streamGenerateContent";
+ }
+
+ public function getHttpMethod(): string
+ {
+ return 'POST';
+ }
+
+ public function getHttpPayload(): string
+ {
+ return (string) $this;
+ }
+
+ /**
+ * @return array{
+ * model: string,
+ * contents: Content[],
+ * safetySettings?: SafetySetting[],
+ * generationConfig?: GenerationConfig,
+ * }
+ */
+ public function jsonSerialize(): array
+ {
+ $arr = [
+ 'model' => $this->modelName->value,
+ 'contents' => $this->contents,
+ ];
+
+ if (!empty($this->safetySettings)) {
+ $arr['safetySettings'] = $this->safetySettings;
+ }
+
+ if ($this->generationConfig) {
+ $arr['generationConfig'] = $this->generationConfig;
+ }
+
+ return $arr;
+ }
+
+ public function __toString(): string
+ {
+ return json_encode($this) ?: '';
+ }
+}