Http client refactoring

Author: ddebowczyk

docs/instructor/polyglot/quickstart.mdx

@@ -1 +1,89 @@
-# Work in progress
+---
+title: 'Quickstart'
+description: 'Start working with LLMs in under 5 minutes'
+---
+
+This guide will help you get started with Polyglot in your PHP project in under 5 minutes.
+
+For detailed setup instructions, see [Setup](setup).
+
+
+## Install Polyglot with Composer
+
+Run following command in your terminal:
+
+```bash
+composer require cognesy/instructor-polyglot
+```
+
+
+## Create and Run Example
+
+### Step 1: Prepare your OpenAI API Key
+
+In this example, we'll use OpenAI as the LLM provider. You can get it from the [OpenAI dashboard](https://platform.openai.com/).
+
+### Step 2: Create a New PHP File
+
+In your project directory, create a new PHP file `test-instructor.php`:
+
+```php
+<?php
+require __DIR__ . '/vendor/autoload.php';
+
+use Cognesy\Instructor\Instructor;
+
+// Set up OpenAI API key
+$apiKey = 'your-openai-api-key';
+putenv("OPENAI_API_KEY=" . $apiKey);
+// WARNING: In real project you should set up API key in .env file.
+
+// Step 1: Define target data structure(s)
+class City {
+    public string $name;
+    public string $country;
+    public int $population;
+}
+
+// Step 2: Use Instructor to run LLM inference
+$city = (new Instructor)->withConnection('openai')->respond(
+    messages: 'What is the capital of France?',
+    responseModel: City::class,
+);
+
+var_dump($city);
+```
+
+<Warning>
+    You should never put your API keys directly in your real project code to avoid getting them compromised. Set them up in your .env file.
+</Warning>
+
+### Step 3: Run the Example
+
+Now, you can run the example:
+
+```bash
+php test-instructor.php
+
+# Output:
+# object(City)#1 (3) {
+#   ["name"]=>
+#   string(5) "Paris"
+#   ["country"]=>
+#   string(6) "France"
+#   ["population"]=>
+#   int(2148000)
+# }
+```
+
+
+## Next Steps
+
+You can start using Instructor in your project right away after installation.
+
+But it's recommended to publish configuration files and prompt templates to your project directory, so you can
+customize the library's behavior and use your own prompt templates.
+
+You should also set up LLM provider API keys in your `.env` file instead of putting them directly in your code.
+
+See [Setup Instructions](setup) for more details.

examples/A02_Advanced/CustomClientParameters/run.php

@@ -34,7 +34,7 @@ class User {
     model: 'deepseek-chat',
     maxTokens: 128,
     httpClient: 'guzzle',
-    providerType: LLMProviderType::OpenAICompatible,
+    providerType: LLMProviderType::OpenAICompatible->value,
 );
 
 // Get Instructor with the default client component overridden with your own

examples/C02_LLMAdvanced/CustomClientParameters/run.php

@@ -28,7 +28,7 @@
     model: 'deepseek-chat',
     maxTokens: 128,
     httpClient: 'guzzle',
-    providerType: LLMProviderType::OpenAICompatible,
+    providerType: LLMProviderType::OpenAICompatible->value,
 );
 
 $answer = (new Inference)

src-polyglot/Embeddings/Data/EmbeddingsConfig.php

@@ -17,7 +17,7 @@ public function __construct(
         public int $maxInputs = 0,
         public array $metadata = [],
         public string $httpClient = '',
-        public ?LLMProviderType $providerType = null,
+        public string $providerType = LLMProviderType::OpenAI->value,
     ) {}
 
     public static function load(string $connection) : EmbeddingsConfig {
@@ -33,7 +33,7 @@ public static function load(string $connection) : EmbeddingsConfig {
             maxInputs: Settings::get('embed', "connections.$connection.maxInputs", 1),
             metadata: Settings::get('embed', "connections.$connection.metadata", []),
             httpClient: Settings::get('embed', "connections.$connection.httpClient", ''),
-            providerType: LLMProviderType::from(Settings::get('embed', "connections.$connection.providerType")),
+            providerType: Settings::get('embed', "connections.$connection.providerType", LLMProviderType::OpenAI->value),
         );
     }
 }

src-polyglot/Embeddings/Embeddings.php

@@ -85,14 +85,14 @@ public function create(string|array $input, array $options = []) : EmbeddingsRes
 
     protected function getDriver(EmbeddingsConfig $config, CanHandleHttp $httpClient) : CanVectorize {
         return match ($config->providerType) {
-            LLMProviderType::Azure => new AzureOpenAIDriver($config, $httpClient, $this->events),
-            LLMProviderType::CohereV1 => new CohereDriver($config, $httpClient, $this->events),
-            LLMProviderType::Gemini => new GeminiDriver($config, $httpClient, $this->events),
-            LLMProviderType::Mistral => new OpenAIDriver($config, $httpClient, $this->events),
-            LLMProviderType::OpenAI => new OpenAIDriver($config, $httpClient, $this->events),
-            LLMProviderType::Ollama => new OpenAIDriver($config, $httpClient, $this->events),
-            LLMProviderType::Jina => new JinaDriver($config, $httpClient, $this->events),
-            default => throw new InvalidArgumentException("Unknown client: {$config->providerType->value}"),
+            LLMProviderType::Azure->value => new AzureOpenAIDriver($config, $httpClient, $this->events),
+            LLMProviderType::CohereV1->value => new CohereDriver($config, $httpClient, $this->events),
+            LLMProviderType::Gemini->value => new GeminiDriver($config, $httpClient, $this->events),
+            LLMProviderType::Mistral->value => new OpenAIDriver($config, $httpClient, $this->events),
+            LLMProviderType::OpenAI->value => new OpenAIDriver($config, $httpClient, $this->events),
+            LLMProviderType::Ollama->value => new OpenAIDriver($config, $httpClient, $this->events),
+            LLMProviderType::Jina->value => new JinaDriver($config, $httpClient, $this->events),
+            default => throw new InvalidArgumentException("Unknown client: {$config->providerType}"),
         };
     }
 }

src-polyglot/Http/Adapters/LaravelResponseAdapter.php

@@ -2,11 +2,11 @@
 
 namespace Cognesy\Polyglot\Http\Adapters;
 
-use Cognesy\Polyglot\Http\Contracts\ResponseAdapter;
+use Cognesy\Polyglot\Http\Contracts\HttpClientResponse;
 use Generator;
 use Illuminate\Http\Client\Response;
 
-class LaravelResponseAdapter implements ResponseAdapter
+class LaravelResponseAdapter implements HttpClientResponse
 {
     public function __construct(
         private Response $response,
@@ -40,20 +40,4 @@ public function streamContents(int $chunkSize = 1): Generator
             yield $stream->read($chunkSize);
         }
     }
-
-//    public function streamContents(int $chunkSize = 1): Generator
-//    {
-//        if (!$this->streaming) {
-//            yield $this->getContents();
-//            return;
-//        }
-//
-//        $resource = StreamWrapper::getResource($this->response->toPsrResponse()->getBody());
-//
-//        while (!feof($resource)) {
-//            yield fread($resource, $chunkSize);
-//        }
-//
-//        fclose($resource);
-//    }
 }

src-polyglot/Http/Adapters/PsrResponseAdapter.php

@@ -2,12 +2,12 @@
 
 namespace Cognesy\Polyglot\Http\Adapters;
 
-use Cognesy\Polyglot\Http\Contracts\ResponseAdapter;
+use Cognesy\Polyglot\Http\Contracts\HttpClientResponse;
 use Generator;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\StreamInterface;
 
-class PsrResponseAdapter implements ResponseAdapter
+class PsrResponseAdapter implements HttpClientResponse
 {
     private ResponseInterface $response;
     private StreamInterface $stream;

src-polyglot/Http/Adapters/SymfonyResponseAdapter.php

@@ -2,12 +2,12 @@
 
 namespace Cognesy\Polyglot\Http\Adapters;
 
-use Cognesy\Polyglot\Http\Contracts\ResponseAdapter;
+use Cognesy\Polyglot\Http\Contracts\HttpClientResponse;
 use Generator;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
-class SymfonyResponseAdapter implements ResponseAdapter
+class SymfonyResponseAdapter implements HttpClientResponse
 {
     private ResponseInterface $response;
     private HttpClientInterface $client;

src-polyglot/Http/Contracts/CanHandleHttp.php

@@ -5,6 +5,5 @@
 
 interface CanHandleHttp
 {
-    public function handle(HttpClientRequest $request) : ResponseAdapter;
-    public function pool(array $requests, ?int $maxConcurrent = null): array;
+    public function handle(HttpClientRequest $request) : HttpClientResponse;
 }

src-polyglot/Http/Contracts/CanHandleRequestPool.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Cognesy\Polyglot\Http\Contracts;
+
+interface CanHandleRequestPool
+{
+    public function pool(array $requests, ?int $maxConcurrent = null): array;
+}