Add solution metadata classes to provide better DX

Author: butschster

src/AgentExecutor/Interceptor/GeneratePromptInterceptor.php

@@ -14,6 +14,8 @@
 
 /**
  * This interceptor is responsible for generating the prompt for the agent.
+ * If the input does not have a prompt, it will generate one using the prompt generator.
+ * After the execution, it will remove temporary messages (which implement LLM\Agents\LLM\Prompt\Chat\TempMessageInterface) from the prompt.
  */
 final readonly class GeneratePromptInterceptor implements ExecutorInterceptorInterface
 {

src/AgentExecutor/Interceptor/InjectOptionsInterceptor.php

@@ -10,6 +10,9 @@
 use LLM\Agents\AgentExecutor\ExecutorInterceptorInterface;
 use LLM\Agents\AgentExecutor\InterceptorHandler;
 
+/**
+ * This interceptor is responsible for injecting the agent's configuration options into the execution options.
+ */
 final readonly class InjectOptionsInterceptor implements ExecutorInterceptorInterface
 {
     public function __construct(

src/AgentExecutor/Interceptor/InjectResponseIntoPromptInterceptor.php

@@ -11,6 +11,9 @@
 use LLM\Agents\LLM\Response\ChatResponse;
 use LLM\Agents\LLM\Response\ToolCalledResponse;
 
+/**
+ * This interceptor is responsible for injecting the LLM response into the prompt history.
+ */
 final class InjectResponseIntoPromptInterceptor implements ExecutorInterceptorInterface
 {
     public function execute(

src/AgentExecutor/Interceptor/InjectToolsInterceptor.php

@@ -16,6 +16,9 @@
 use LLM\Agents\Tool\ToolInterface;
 use LLM\Agents\Tool\ToolRepositoryInterface;
 
+/**
+ * This interceptor is responsible for injecting the tools into the prompt if the agent has linked tools.
+ */
 final readonly class InjectToolsInterceptor implements ExecutorInterceptorInterface
 {
     public function __construct(

src/AgentExecutor/Interceptor/TokenLimitRetryInterceptor.php

@@ -10,6 +10,10 @@
 use LLM\Agents\AgentExecutor\InterceptorHandler;
 use LLM\Agents\LLM\Exception\LimitExceededException;
 
+/**
+ * This interceptor is responsible for retrying the execution if the token limit is exceeded.
+ * It will increment the limit by a specified step and retry the execution.
+ */
 final readonly class TokenLimitRetryInterceptor implements ExecutorInterceptorInterface
 {
     public function __construct(

src/AgentExecutor/Interceptor/ToolExecutorInterceptor.php

@@ -14,6 +14,13 @@
 use LLM\Agents\LLM\Response\ToolCalledResponse;
 use LLM\Agents\Tool\ToolExecutor;
 
+/**
+ * This interceptor is responsible for calling the tools if LLM asks for it. After calling the tools, it adds the
+ * tools responses to the prompt history and return the result of tools execution to the LLM.
+ *
+ * If the option 'return_tool_result' is set to true, the interceptor will return the tools result instead of adding
+ * it to the prompt.
+ */
 final readonly class ToolExecutorInterceptor implements ExecutorInterceptorInterface
 {
     public function __construct(

src/Solution/AgentLink.php

@@ -4,6 +4,9 @@
 
 namespace LLM\Agents\Solution;
 
+/**
+ * Represents a link to another agent.
+ */
 class AgentLink extends Solution
 {
     public function __construct(

src/Solution/Metadata/DtoOutputFormatter.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LLM\Agents\Solution\Metadata;
+
+/**
+ * Instruct an agent to use a specific DTO class to format the output.
+ * If the class is DTO it must implement \JsonSerializable.
+ */
+final readonly class DtoOutputFormatter extends Option
+{
+    /**
+     * @param class-string $dtoClass DTO class or an Enum
+     */
+    public function __construct(string $dtoClass)
+    {
+        parent::__construct(
+            key: 'output_formatter',
+            content: $dtoClass,
+        );
+    }
+}

src/Solution/Metadata/Memory.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LLM\Agents\Solution\Metadata;
+
+use LLM\Agents\Solution\MetadataType;
+use LLM\Agents\Solution\SolutionMetadata;
+
+/**
+ * Add some memory to an agent.
+ */
+final readonly class Memory extends SolutionMetadata
+{
+    public function __construct(
+        \Stringable|int|string $content,
+        ?string $key = 'memory',
+    ) {
+        parent::__construct(
+            type: MetadataType::Memory,
+            key: $key,
+            content: $content,
+        );
+    }
+}

src/Solution/Metadata/Option.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LLM\Agents\Solution\Metadata;
+
+use LLM\Agents\Solution\MetadataType;
+use LLM\Agents\Solution\SolutionMetadata;
+
+readonly class Option extends SolutionMetadata
+{
+    public function __construct(
+        string $key,
+        mixed $content,
+    ) {
+        parent::__construct(
+            type: MetadataType::Configuration,
+            key: $key,
+            content: $content,
+        );
+    }
+}