Merge pull request #10 from llm-agents-php/feature/embeddings

Adds embeddings

README.md

@@ -104,10 +104,10 @@ class SiteStatusCheckerAgent extends AgentAggregate
 Now, let's implement the tool used by this agent:
 
 ```php
-use LLM\Agents\Tool\Tool;
+use LLM\Agents\Tool\PhpTool;
 use LLM\Agents\Tool\ToolLanguage;
 
-class CheckSiteAvailabilityTool extends Tool
+class CheckSiteAvailabilityTool extends PhpTool
 {
  public const NAME = 'check_site_availability';
 
@@ -217,7 +217,7 @@ execution.
 Here's an example of how you might call the linked agent:
 
 ```php
-use LLM\Agents\Tool\Tool;
+use LLM\Agents\Tool\PhpTool;
 use LLM\Agents\Agent\AgentExecutor;
 use LLM\Agents\LLM\Prompt\Chat\ToolCallResultMessage;
 use LLM\Agents\LLM\Response\ToolCalledResponse;
@@ -227,7 +227,7 @@ use LLM\Agents\Tool\ToolLanguage;
 /**
  * @extends PhpTool<AskAgentInput>
  */
-final class AskAgentTool extends Tool
+final class AskAgentTool extends PhpTool
 {
  public const NAME = 'ask_agent';
 
@@ -735,44 +735,18 @@ class PromptGeneratorBootloader extends Bootloader
 
 This class is responsible for handling conversions between JSON schemas and PHP objects.
 
-Here's an example implementation of the `LLM\Agents\Tool\SchemaMapperInterface`:
+We provide a schema mapper package that you can use to implement the `SchemaMapperInterface` in your project. This
+package is a super handy JSON Schema Mapper for the LLM Agents project.
 
-```php
-use CuyZ\Valinor\Mapper\TreeMapper;
-use LLM\Agents\Tool\SchemaMapperInterface;
-use Spiral\JsonSchemaGenerator\Generator as JsonSchemaGenerator;
-
-final readonly class SchemaMapper implements SchemaMapperInterface
-{
- public function __construct(
- private JsonSchemaGenerator $generator,
- private TreeMapper $mapper,
- ) {}
-
- public function toJsonSchema(string $class): array
- {
- if (json_validate($class)) {
- return json_decode($class, associative: true);
- }
-
- if (class_exists($class)) {
- return $this->generator->generate($class)->jsonSerialize();
- }
+**To install the package:**
 
- throw new \InvalidArgumentException("Invalid class or JSON schema provided: $class");
- }
-
- public function toObject(string $json, ?string $class = null): object
- {
- if ($class === null) {
- return json_decode($json, associative: false);
- }
-
- return $this->mapper->map($class, json_decode($json, associative: true));
- }
-}
+```bash
+composer require llm-agents/json-schema-mapper
 ```
 
+> **Note:** Read full documentation of the `llm-agents/json-schema-mapper`
+> package [here](https:/llm-agents-php/schema-mapper)
+
 ### → ContextFactoryInterface
 
 It provides a clean way to pass execution-specific data through the system without tightly coupling components or overly

src/Agent/Agent.php

@@ -9,6 +9,13 @@
 
 final class Agent extends Solution
 {
+ /**
+ * @param string $key The unique key of the agent that is used to retrieve it
+ * @param string $name The name of the agent
+ * @param string $description The short description
+ * @param string $instruction The initial instruction for the agent to interact with the user
+ * @param bool $isActive
+ */
  public function __construct(
  public readonly string $key,
  string $name,

src/Agent/AgentAggregate.php

@@ -6,7 +6,9 @@
 
 use LLM\Agents\Agent\Exception\AgentModelException;
 use LLM\Agents\Agent\Exception\MissingModelException;
+use LLM\Agents\Embeddings\HasLinkedContextSourcesInterface;
 use LLM\Agents\Solution\AgentLink;
+use LLM\Agents\Solution\ContextSourceLink;
 use LLM\Agents\Solution\MetadataType;
 use LLM\Agents\Solution\Model;
 use LLM\Agents\Solution\Solution;
@@ -17,7 +19,10 @@
 /**
  * @psalm-type TAssociation = Solution|Model|ToolLink|AgentLink
  */
-class AgentAggregate implements AgentInterface
+class AgentAggregate implements AgentInterface,
+ HasLinkedAgentsInterface,
+ HasLinkedToolsInterface,
+ HasLinkedContextSourcesInterface
 {
  /**
  * @var array<TAssociation>
@@ -56,6 +61,14 @@ public function getTools(): array
  );
  }
 
+ public function getContextSources(): array
+ {
+ return \array_filter(
+ $this->associations,
+ static fn(Solution $association): bool => $association instanceof ContextSourceLink,
+ );
+ }
+
  public function getAgents(): array
  {
  return \array_filter(

src/Agent/AgentFactoryInterface.php

@@ -4,7 +4,25 @@
 
 namespace LLM\Agents\Agent;
 
+namespace LLM\Agents\Agent;
+
+/**
+ * It defines a contract for creating instances of agents. It encapsulates the complex process of agent
+ * initialization, configuration, and setup.
+ *
+ * Purpose:
+ * 1. Abstraction: It provides a level of abstraction between the agent creation
+ * process and the rest of the application, allowing for different implementation
+ * strategies without affecting the client code.
+ *
+ * 2. Flexibility: By using a factory interface, the framework can support multiple
+ * types of agents or different initialization strategies for agents without
+ * changing the core logic.
+ */
 interface AgentFactoryInterface
 {
+ /**
+ * Create and return a fully initialized agent instance.
+ */
  public function create(): AgentInterface;
 }

src/Agent/AgentInterface.php

@@ -11,42 +11,67 @@
 use LLM\Agents\Solution\ToolLink;
 
 /**
+ * Represents an AI agent capable of performing tasks, making decisions,
+ * and interacting with various tools and other agents.
  * @psalm-type TAssociation = Solution|Model|ToolLink|AgentLink
  */
 interface AgentInterface
 {
+ /**
+ * Get the unique key identifier for the agent.
+ */
  public function getKey(): string;
 
+ /**
+ * Get the human-readable name of the agent.
+ */
  public function getName(): string;
 
+ /**
+ * Get the description of the agent's purpose and capabilities.
+ */
  public function getDescription(): ?string;
 
- public function getInstruction(): string;
-
  /**
- * @return array<ToolLink>
+ * Get the primary instruction set for the agent.
  */
- public function getTools(): array;
+ public function getInstruction(): string;
 
  /**
- * @return array<AgentLink>
+ * Get the language model associated with this agent.
  */
- public function getAgents(): array;
-
  public function getModel(): Model;
 
  /**
+ * Get the agent's memory, containing learned information and experiences.
+ *
  * @return array<SolutionMetadata>
  */
  public function getMemory(): array;
 
  /**
+ * Get the list of predefined prompts for the agent.
+ *
  * @return array<SolutionMetadata>
  */
  public function getPrompts(): array;
 
  /**
+ * Get the agent's configuration settings.
+ *
+ * This method returns an array of configuration settings for the agent,
+ * which can include parameters for the LLM (Language Model) client configuration.
+ * These settings may affect how the agent interacts with the language model,
+ * including parameters like temperature, max tokens, and other model-specific options.
+ *
  * @return array<SolutionMetadata>
+ *
+ * @example
+ * [
+ * new SolutionMetadata(MetadataType::Configuration, 'temperature', 0.7),
+ * new SolutionMetadata(MetadataType::Configuration, 'max_tokens', 150),
+ * new SolutionMetadata(MetadataType::Configuration, 'top_p', 1),
+ * ]
  */
  public function getConfiguration(): array;
 }

src/Agent/AgentRegistryInterface.php

@@ -6,14 +6,25 @@
 
 use LLM\Agents\Agent\Exception\AgentAlreadyRegisteredException;
 
+/**
+ * It defines the contract for a registry that manages the registration of agents.
+ *
+ * Purpose:
+ * - Provide a centralized mechanism for registering new agents in the system.
+ * - Allow for dynamic addition of agents at runtime.
+ */
 interface AgentRegistryInterface
 {
  /**
+ * Register a new agent in the system.
+ *
  * @throws AgentAlreadyRegisteredException
  */
  public function register(AgentInterface $agent): void;
 
  /**
+ * Retrieve all registered agents.
+ *
  * @return AgentInterface[]
  */
  public function all(): iterable;

src/Agent/AgentRepositoryInterface.php

@@ -6,12 +6,32 @@
 
 use LLM\Agents\Agent\Exception\AgentNotFoundException;
 
+/**
+ * It defines the contract for a repository that provides access to registered agents.
+ *
+ * Purpose:
+ * - Provide a standardized way to retrieve specific agents by their unique keys.
+ * - Allow checking for the existence of agents in the system.
+ *
+ * This interface is essential for components that need to work with specific
+ * agents. It abstracts the storage and retrieval mechanisms, allowing for
+ * different implementations (e.g., in-memory, database-backed) without
+ * affecting the consumers of the interface.
+ */
 interface AgentRepositoryInterface
 {
  /**
+ * Retrieve an agent by its unique key.
+ *
+ * @param non-empty-string $key The unique key of the agent to retrieve.
  * @throws AgentNotFoundException
  */
  public function get(string $key): AgentInterface;
 
+ /**
+ * Check if an agent with the given key exists in the repository.
+ *
+ * @param non-empty-string $key The key to check for existence.
+ */
  public function has(string $key): bool;
 }

src/Agent/Execution.php

@@ -7,8 +7,15 @@
 use LLM\Agents\LLM\Prompt\Chat\PromptInterface;
 use LLM\Agents\LLM\Response\Response;
 
+/**
+ * Represents the result of an agent's execution, including the response and the prompt used.
+ */
 final readonly class Execution
 {
+ /**
+ * @param Response $result The response from the agent's execution.
+ * @param PromptInterface $prompt The prompt used for the execution.
+ */
  public function __construct(
  public Response $result,
  public PromptInterface $prompt,

src/Agent/HasLinkedAgentsInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LLM\Agents\Agent;
+
+use LLM\Agents\Solution\AgentLink;
+
+interface HasLinkedAgentsInterface
+{
+ /**
+ * Get the list of other agents this agent can interact with.
+ *
+ * @return array<AgentLink>
+ */
+ public function getAgents(): array;
+}

src/Agent/HasLinkedToolsInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LLM\Agents\Agent;
+
+use LLM\Agents\Solution\ToolLink;
+
+interface HasLinkedToolsInterface
+{
+ /**
+ * Get the list of tools available to the agent.
+ *
+ * @return array<ToolLink>
+ */
+ public function getTools(): array;
+}