[Vector] Introduce to VectorTools class

src/Agent.php

@@ -257,4 +257,28 @@ public function withHost(string $host): self
 
         return $this;
     }
+
+    /**
+     * Embedding
+     * 
+     * @param string $model
+     * param string $content
+     */
+    public function embedding(string $model, string $content): array
+    {
+        return $this->agentClass::create(
+            key: $this->key,
+            model: $model,
+            config: ['host' => $this->host]
+        )
+            ->execute([], true, $content)->asVectors()[0]->getData();
+    }
+
+    /**
+     * getAgentClass
+     */
+    public function getAgentClass(): string
+    {
+        return $this->agentClass;
+    }
 }

src/AgentFactory/Agent/Gemini.php

@@ -69,9 +69,10 @@ public function setMessage(array $messages): mixed
      *
      * @param array<string, mixed> $params
      * @param bool $complete
+     * @param ?string $textInput
      * @return mixed
      */
-    public function execute(array $params, bool $complete = false): mixed
+    public function execute(array $params, bool $complete = false,?string $textInput = null): mixed
     {
         $params = $this->normalizeParams($params);
 

src/AgentFactory/Agent/OpenAI.php

@@ -69,11 +69,12 @@ public function setMessage(array $messages): mixed
      *
      * @param array<string, mixed> $params
      * @param bool $complete
+     * @param ?string $textInput
      * @return mixed
      */
-    public function execute(array $params, bool $complete = false): mixed
+    public function execute(array $params, bool $complete = false, ?string $textInput = null): mixed
     {
-        $result = $this->platform->invoke($this->model, $this->messages, $params);
+        $result = $this->platform->invoke($this->model, $textInput ?? $this->messages, $params);
         return $complete ? $result : $result->asText();
     }
 

src/AgentFactory/Agent/SelfHost.php

@@ -103,9 +103,10 @@ public function setMessage(array $messages): mixed
      *
      * @param array<string, mixed> $params
      * @param bool $complete
+     * @param ?string $textInput
      * @return mixed
      */
-    public function execute(array $params, bool $complete = false): mixed
+    public function execute(array $params, bool $complete = false, ?string $textInput = null): mixed
     {
         $result = $this->platform->invoke($this->model, $this->messages, $params);
         return $complete ? $result : $result->asText();

src/AgentFactory/AgentInterface.php

@@ -29,9 +29,10 @@ public function setMessage(array $messages): mixed;
      *
      * @param array $params
      * @param bool $complete
+     * @param ?string $textInput
      * @return mixed 
      */
-    public function execute(array $params, bool $complete = false): mixed;
+    public function execute(array $params, bool $complete = false, ?string $textInput = null): mixed;
 
     /**
      * Converts raw message data into a MessageBag instance.

src/Vector/VectorTools.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Doppar\AI\Vector;
+
+use Doppar\AI\Agent;
+use Doppar\AI\AgentFactory\Agent\OpenAI;
+
+/**
+ * Helper class providing vector utilities for RAG (Retrieval Augmented Generation).
+ */
+class VectorTools
+{
+    /**
+     * Compute the cosine similarity between two numeric vectors.
+     *
+     * @param array<int,float> $vecA
+     * @param array<int,float> $vecB
+     *
+     * @return float
+     */
+    static function cosineSimilarity(array $vecA, array $vecB): float {
+        $dot = 0;
+        $normA = 0;
+        $normB = 0;
+        foreach ($vecA as $i => $val) {
+            $dot += $val * $vecB[$i];
+
+            $normA += $val * $val;
+            $normB += $vecB[$i] * $vecB[$i];
+        }
+        return $dot / (sqrt($normA) * sqrt($normB) + 1e-10);
+    }
+
+    /**
+     * Retrieve the most relevant context text for a given question embedding.
+     *
+     * @param array<int,array{vector:array<int,float>,content:string}> $context
+     * @param array<int,float> $questionVector
+     *
+     * @return string
+     */
+    static function getContext(array $context, array $questionVector): string
+    {
+        usort($context, function($a, $b) use ($questionVector) {
+            return VectorTools::cosineSimilarity($b['vector'], $questionVector) <=> VectorTools::cosineSimilarity($a['vector'], $questionVector);
+        });
+
+        $topChunks = array_slice($context, 0, 3);
+
+        return implode("\n\n", array_column($topChunks, 'content'));
+    }
+
+    /**
+     * Generate an embedding vector for the given text using the provided Agent.
+     *
+     * @param Agent $agent
+     * @param string $model
+     * @param string $content
+     *
+     * @return array<int,float>
+     */
+    static function embedding(Agent $agent, string $model, string $content): array
+    {
+        $agentClass = $agent->getAgentClass();
+
+        match ($agentClass) {
+            OpenAI::class => null,
+            default => throw new \RuntimeException('Embeddings are only supported for OpenAI agent.'),
+        };
+
+        return $agent->embedding($model, $content);
+    }
+}