Added docs to HTTP & LLM packages

Author: ddebowczyk

src-polyglot/Embeddings/Contracts/CanVectorize.php

@@ -3,7 +3,19 @@
 
 use Cognesy\Polyglot\Embeddings\EmbeddingsResponse;
 
+/**
+ * Interface CanVectorize
+ *
+ * Defines the contract for embedding generation services
+ */
 interface CanVectorize
 {
+    /**
+     * Generate embeddings for the input
+     *
+     * @param array $input
+     * @param array $options
+     * @return EmbeddingsResponse
+     */
     public function vectorize(array $input, array $options = []) : EmbeddingsResponse;
 }

src-polyglot/Embeddings/Data/Vector.php

@@ -2,6 +2,11 @@
 
 namespace Cognesy\Polyglot\Embeddings\Data;
 
+/**
+ * Class Vector
+ *
+ * Represents an embedding - vector of floating point values
+ */
 class Vector
 {
     public const METRIC_COSINE = 'cosine';
@@ -14,15 +19,28 @@ public function __construct(
         private int|string $id = 0,
     ) {}
 
-    /** @return float[] */
+    /**
+     * Get the vector values
+     * @return float[]
+     */
     public function values() : array {
         return $this->values;
     }
 
+    /**
+     * Get the vector ID
+     * @return int|string
+     */
     public function id() : int|string {
         return $this->id;
     }
 
+    /**
+     * Compare this vector to another vector using a metric
+     * @param Vector $vector
+     * @param string $metric
+     * @return float
+     */
     public function compareTo(Vector $vector, string $metric) : float {
         return match ($metric) {
             self::METRIC_COSINE => self::cosineSimilarity($this->values, $vector->values),
@@ -33,6 +51,7 @@ public function compareTo(Vector $vector, string $metric) : float {
     }
 
     /**
+     * Calculate the cosine similarity between two vectors
      * @param float[] $v1
      * @param float[] $v2
      */
@@ -51,17 +70,8 @@ public static function cosineSimilarity(array $v1, array $v2) : float {
         return $dotProduct / ($magnitudeV1 * $magnitudeV2);
     }
 
-//    private function cosineSimilarity(array $vec1, array $vec2) : float {
-//        $dotProduct = array_sum(array_map(fn($a, $b) => $a * $b, $vec1, $vec2));
-//        $magnitude1 = sqrt(array_sum(array_map(fn($a) => $a * $a, $vec1)));
-//        $magnitude2 = sqrt(array_sum(array_map(fn($b) => $b * $b, $vec2)));
-//        if ($magnitude1 * $magnitude2 == 0) {
-//            return 0;
-//        }
-//        return $dotProduct / ($magnitude1 * $magnitude2);
-//    }
-
     /**
+     * Calculate the Euclidean distance between two vectors
      * @param float[] $v1
      * @param float[] $v2
      */
@@ -75,6 +85,7 @@ public static function euclideanDistance(array $v1, array $v2) : float {
     }
 
     /**
+     * Calculate the dot product between two vectors
      * @param float[] $v1
      * @param float[] $v2
      */

src-polyglot/Embeddings/Embeddings.php

@@ -17,6 +17,9 @@
 use Cognesy\Utils\Settings;
 use InvalidArgumentException;
 
+/**
+ * Embeddings is a facade responsible for generating embeddings for provided input data
+ */
 class Embeddings
 {
     use HasFinders;
@@ -43,34 +46,65 @@ public function __construct(
 
     // PUBLIC ///////////////////////////////////////////////////
 
+    /**
+     * Configures the Embeddings instance with the given connection name.
+     * @param string $connection
+     * @return $this
+     */
     public function withConnection(string $connection) : self {
         $this->config = EmbeddingsConfig::load($connection);
         $this->driver = $this->getDriver($this->config, $this->httpClient);
         return $this;
     }
 
+    /**
+     * Configures the Embeddings instance with the given configuration.
+     * @param EmbeddingsConfig $config
+     * @return $this
+     */
     public function withConfig(EmbeddingsConfig $config) : self {
         $this->config = $config;
         $this->driver = $this->getDriver($this->config, $this->httpClient);
         return $this;
     }
 
+    /**
+     * Configures the Embeddings instance with the given model name.
+     * @param string $model
+     * @return $this
+     */
     public function withModel(string $model) : self {
         $this->config->model = $model;
         return $this;
     }
 
+    /**
+     * Configures the Embeddings instance with the given HTTP client.
+     * @param CanHandleHttp $httpClient
+     * @return $this
+     */
     public function withHttpClient(CanHandleHttp $httpClient) : self {
         $this->httpClient = $httpClient;
         $this->driver = $this->getDriver($this->config, $this->httpClient);
         return $this;
     }
 
+    /**
+     * Configures the Embeddings instance with the given driver.
+     * @param CanVectorize $driver
+     * @return $this
+     */
     public function withDriver(CanVectorize $driver) : self {
         $this->driver = $driver;
         return $this;
     }
 
+    /**
+     * Generates embeddings for the provided input data.
+     * @param string|array $input
+     * @param array $options
+     * @return EmbeddingsResponse
+     */
     public function create(string|array $input, array $options = []) : EmbeddingsResponse {
         if (is_string($input)) {
             $input = [$input];
@@ -83,6 +117,12 @@ public function create(string|array $input, array $options = []) : EmbeddingsRes
 
     // INTERNAL /////////////////////////////////////////////////
 
+    /**
+     * Returns the driver for the specified configuration.
+     * @param EmbeddingsConfig $config
+     * @param CanHandleHttp $httpClient
+     * @return CanVectorize
+     */
     protected function getDriver(EmbeddingsConfig $config, CanHandleHttp $httpClient) : CanVectorize {
         return match ($config->providerType) {
             LLMProviderType::Azure->value => new AzureOpenAIDriver($config, $httpClient, $this->events),

src-polyglot/Embeddings/EmbeddingsResponse.php

@@ -5,6 +5,9 @@
 use Cognesy\Polyglot\Embeddings\Data\Vector;
 use Cognesy\Polyglot\LLM\Data\Usage;
 
+/**
+ * EmbeddingsResponse represents the response from an embeddings request
+ */
 class EmbeddingsResponse
 {
     public function __construct(
@@ -13,23 +16,40 @@ public function __construct(
         public ?Usage $usage,
     ) {}
 
+    /**
+     * Get the first vector
+     * @return Vector
+     */
     public function first() : Vector {
         return $this->vectors[0];
     }
 
+    /**
+     * Get the last vector
+     * @return Vector
+     */
     public function last() : Vector {
         return $this->vectors[count($this->vectors) - 1];
     }
 
+    /**
+     * Get all vectors
+     * @return Vector[]
+     */
     public function all() : array {
         return $this->vectors;
     }
 
+    /**
+     * Get the number of vectors
+     * @return Usage
+     */
     public function usage() : Usage {
         return $this->usage;
     }
 
     /**
+     * Split the vectors into two EmbeddingsResponse objects
      * @param int $index
      * @return EmbeddingsResponse[]
      */
@@ -46,13 +66,21 @@ public function split(int $index) : array {
         ];
     }
 
+    /**
+     * Get the values of all vectors
+     * @return array
+     */
     public function toValuesArray() : array {
         return array_map(
             fn(Vector $vector) => $vector->values(),
             $this->vectors
         );
     }
 
+    /**
+     * Get the total number of tokens
+     * @return int
+     */
     public function totalTokens() : int {
         return $this->usage()->total();
     }

src-polyglot/Embeddings/Traits/HasFinders.php

@@ -3,8 +3,20 @@
 
 use Cognesy\Polyglot\Embeddings\Data\Vector;
 
+/**
+ * Trait HasFinders
+ *
+ * Provides methods for finding similar documents
+ */
 trait HasFinders
 {
+    /**
+     * Find the most similar documents to the query
+     * @param string $query
+     * @param array $documents
+     * @param int $topK
+     * @return array
+     */
     public function findSimilar(string $query, array $documents, int $topK = 5) : array {
         // generate embeddings for query and documents (in a single request)
         [$queryVector, $docVectors] = $this->create(array_merge([$query], $documents))->split(1);
@@ -20,6 +32,13 @@ public function findSimilar(string $query, array $documents, int $topK = 5) : ar
         ], array_keys($matches));
     }
 
+    /**
+     * Find the top K most similar documents to the query vector
+     * @param array $queryVector
+     * @param array $documentVectors
+     * @param int $n
+     * @return array
+     */
     public static function findTopK(array $queryVector, array $documentVectors, int $n = 5) : array {
         $similarity = [];
         foreach ($documentVectors as $i => $vector) {
@@ -29,11 +48,3 @@ public static function findTopK(array $queryVector, array $documentVectors, int
         return array_slice($similarity, 0, $n, true);
     }
 }
-
-//if ($this->clientType !== ClientType::Jina && $this->model === 'jina-colbert-v2') {
-//    $docVectors = $this->make($documents, ['options' => ['input_type' => 'document']]);
-//    $queryVector = $this->make($query, ['options' => ['input_type' => 'query']]);
-//} else {
-//    $docVectors = $this->make($documents);
-//    $queryVector = $this->make($query);
-//}

…Http/Adapters/LaravelResponseAdapter.php …ot/Http/Adapters/LaravelHttpResponse.phpsrc-polyglot/Http/Adapters/LaravelResponseAdapter.php renamed to src-polyglot/Http/Adapters/LaravelHttpResponse.php src-polyglot/Http/Adapters/LaravelResponseAdapter.php renamed to src-polyglot/Http/Adapters/LaravelHttpResponse.php

@@ -6,28 +6,54 @@
 use Generator;
 use Illuminate\Http\Client\Response;
 
-class LaravelResponseAdapter implements HttpClientResponse
+/**
+ * Class LaravelHttpResponse
+ *
+ * Implements HttpClientResponse contract for Laravel HTTP client
+ */
+class LaravelHttpResponse implements HttpClientResponse
 {
     public function __construct(
         private Response $response,
         private bool $streaming = false
     ) {}
 
+    /**
+     * Get the response status code
+     *
+     * @return int
+     */
     public function getStatusCode(): int
     {
         return $this->response->status();
     }
 
+    /**
+     * Get the response headers
+     *
+     * @return array
+     */
     public function getHeaders(): array
     {
         return $this->response->headers();
     }
 
+    /**
+     * Get the response content
+     *
+     * @return string
+     */
     public function getContents(): string
     {
         return $this->response->body();
     }
 
+    /**
+     * Read chunks of the stream
+     *
+     * @param int $chunkSize
+     * @return Generator<string>
+     */
     public function streamContents(int $chunkSize = 1): Generator
     {
         if (!$this->streaming) {