Allow custom streaming client

Author: erdemkose

README.md

@@ -26,6 +26,10 @@ _This library is not developed or endorsed by Google._
  - [Streaming Chat Session](#streaming-chat-session)
  - [Tokens counting](#tokens-counting)
  - [Listing models](#listing-models)
+ - [Advanced Usages](#advanced-usages)
+ - [Safety Settings and Generation Configuration](#safety-settings-and-generation-configuration)
+ - [Using your own HTTP client](#using-your-own-http-client)
+ - [Using your own HTTP client for streaming responses](#using-your-own-http-client-for-streaming-responses)
 
 ## Installation
 
@@ -173,7 +177,7 @@ $callback = function (GenerateContentResponse $response): void {
 
 $client->geminiPro()->generateContentStream(
  $callback,
- new TextPart('PHP in less than 100 chars')
+ [new TextPart('PHP in less than 100 chars')],
 );
 // Response #0
 // PHP: a versatile, general-purpose scripting language for web development, popular for
@@ -287,3 +291,79 @@ print_r($response->models);
 // )
 //]
 ```
+
+### Advanced Usages
+
+#### Safety Settings and Generation Configuration
+
+```php
+$client = new GeminiAPI\Client('GEMINI_API_KEY');
+$safetySetting = new GeminiAPI\SafetySetting(
+ HarmCategory::HARM_CATEGORY_HATE_SPEECH,
+ HarmBlockThreshold::BLOCK_LOW_AND_ABOVE,
+);
+$generationConfig = (new GeminiAPI\GenerationConfig())
+ ->withCandidateCount(1)
+ ->withMaxOutputTokens(40)
+ ->withTemperature(0.5)
+ ->withTopK(40)
+ ->withTopP(0.6)
+ ->withStopSequences(['STOP']);
+
+$response = $client->geminiPro()
+ ->withAddedSafetySetting($safetySetting)
+ ->withGenerationConfig($generationConfig)
+ ->generateContent(
+ new TextPart('PHP in less than 100 chars')
+ );
+```
+
+#### Using your own HTTP client
+
+```php
+$guzzle = new GuzzleHttp\Client([
+ 'proxy' => 'http://localhost:8125',
+]);
+$client = new GeminiAPI\Client('GEMINI_API_KEY', $guzzle);
+
+$response = $client->geminiPro()->generateContent(
+ new TextPart('PHP in less than 100 chars')
+);
+```
+
+#### Using your own HTTP client for streaming responses
+
+> Requires `curl` extension to be enabled
+
+Since streaming responses are fetched using `curl` extension, they cannot use the custom HTTP client passed to the Gemini Client.
+You need to pass a `CurlHandler` if you want to override connection options.
+
+The following curl options will be overwritten by the Gemini Client.
+
+- `CURLOPT_URL`
+- `CURLOPT_POST`
+- `CURLOPT_POSTFIELDS`
+- `CURLOPT_WRITEFUNCTION`
+
+You can also pass the headers you want to be used in the requests.
+
+```php
+$client = new GeminiAPI\Client('GEMINI_API_KEY');
+
+$callback = function (GenerateContentResponse $response): void {
+ print $response->text();
+};
+
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_PROXY, 'http://localhost:8125');
+
+$client->withRequestHeaders([
+ 'User-Agent' => 'My Gemini-backed app'
+ ])
+ ->geminiPro()
+ ->generateContentStream(
+ $callback,
+ [new TextPart('PHP in less than 100 chars')],
+ $ch,
+ );
+```

src/Client.php

@@ -27,6 +27,7 @@
 use Psr\Http\Message\StreamFactoryInterface;
 use RuntimeException;
 
+use function array_map;
 use function curl_close;
 use function curl_exec;
 use function curl_getinfo;
@@ -35,10 +36,17 @@
 use function extension_loaded;
 use function json_decode;
 use function sprintf;
+use function strtolower;
 
 class Client implements GeminiClientInterface
 {
  private string $baseUrl = 'https://generativelanguage.googleapis.com';
+
+ /**
+ * @var array<string, string>
+ */
+ private array $requestHeaders = [];
+
  public function __construct(
  private readonly string $apiKey,
  private ?HttpClientInterface $client = null,
@@ -88,13 +96,16 @@ public function generateContent(GenerateContentRequest $request): GenerateConten
  }
 
  /**
+ * @param GenerateContentStreamRequest $request
  * @param callable(GenerateContentResponse): void $callback
+ * @param CurlHandle|null $curl
  * @throws BadMethodCallException
  * @throws RuntimeException
  */
  public function generateContentStream(
  GenerateContentStreamRequest $request,
  callable $callback,
+ ?CurlHandle $curl = null,
  ): void {
  if (!extension_loaded('curl')) {
  throw new BadMethodCallException('Gemini API requires `curl` extension for streaming responses');
@@ -120,18 +131,25 @@ public function generateContentStream(
  );
  };
 
- $ch = curl_init("{$this->baseUrl}/v1/{$request->getOperation()}");
+ $ch = $curl ?? curl_init();
 
  if ($ch === false) {
  throw new RuntimeException('Gemini API cannot initialize streaming content request');
  }
 
+ $headers = $this->requestHeaders + [
+ 'content-type' => 'application/json',
+ self::API_KEY_HEADER_NAME => $this->apiKey,
+ ];
+ $headerLines = [];
+ foreach ($headers as $name => $value) {
+ $headerLines[] = "{$name}: {$value}";
+ }
+
+ curl_setopt($ch, CURLOPT_URL, "{$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_HTTPHEADER, $headerLines);
  curl_setopt($ch, CURLOPT_WRITEFUNCTION, $writeFunction);
  curl_exec($ch);
  curl_close($ch);
@@ -179,6 +197,18 @@ public function withBaseUrl(string $baseUrl): self
  return $clone;
  }
 
+ /**
+ * @param array<string, string> $headers
+ * @return self
+ */
+ public function withRequestHeaders(array $headers): self
+ {
+ $clone = clone $this;
+ $clone->requestHeaders = array_map(strtolower(...), $headers);
+
+ return $clone;
+ }
+
  /**
  * @throws ClientExceptionInterface
  */
@@ -193,6 +223,10 @@ private function doRequest(RequestInterface $request): string
  ->createRequest($request->getHttpMethod(), $uri)
  ->withAddedHeader(self::API_KEY_HEADER_NAME, $this->apiKey);
 
+ foreach ($this->requestHeaders as $name => $value) {
+ $httpRequest = $httpRequest->withAddedHeader($name, $value);
+ }
+
  $payload = $request->getHttpPayload();
  if (!empty($payload)) {
  $stream = $this->streamFactory->createStream($payload);

src/GenerativeModel.php

@@ -5,6 +5,7 @@
 namespace GeminiAPI;
 
 use BadMethodCallException;
+use CurlHandle;
 use GeminiAPI\Enums\ModelName;
 use GeminiAPI\Enums\Role;
 use GeminiAPI\Requests\CountTokensRequest;
@@ -62,26 +63,33 @@ public function generateContentWithContents(array $contents): GenerateContentRes
 
  /**
  * @param callable(GenerateContentResponse): void $callback
- * @param PartInterface ...$parts
+ * @param PartInterface[] $parts
+ * @param CurlHandle|null $ch
  * @return void
- * @throws BadMethodCallException
  */
  public function generateContentStream(
  callable $callback,
- PartInterface ...$parts,
+ array $parts,
+ ?CurlHandle $ch = null,
  ): void {
+ $this->ensureArrayOfType($parts, PartInterface::class);
+
  $content = new Content($parts, Role::User);
 
- $this->generateContentStreamWithContents($callback, [$content]);
+ $this->generateContentStreamWithContents($callback, [$content], $ch);
  }
 
  /**
  * @param callable(GenerateContentResponse): void $callback
  * @param Content[] $contents
+ * @param CurlHandle|null $ch
  * @return void
  */
- public function generateContentStreamWithContents(callable $callback, array $contents): void
- {
+ public function generateContentStreamWithContents(
+ callable $callback,
+ array $contents,
+ ?CurlHandle $ch = null,
+ ): void {
  $this->ensureArrayOfType($contents, Content::class);
 
  $request = new GenerateContentStreamRequest(
@@ -91,7 +99,7 @@ public function generateContentStreamWithContents(callable $callback, array $con
  $this->generationConfig,
  );
 
- $this->client->generateContentStream($request, $callback);
+ $this->client->generateContentStream($request, $callback, $ch);
  }
 
  public function startChat(): ChatSession