Add PHPDoc to all classes and public methods

Document all contracts, value objects, middleware, exceptions, agent builder
with @param, @return, and @throws annotations.

Author: MarcelloDuarte

src/Agent.php

@@ -22,6 +22,16 @@
 use PapiAI\Core\Contracts\ToolInterface;
 use PapiAI\Core\Schema\Schema;
 
+/**
+ * Core agent implementation that orchestrates LLM interactions and tool execution.
+ *
+ * Manages the agentic loop: sending prompts to the provider, executing tool calls,
+ * feeding results back, and repeating until the model produces a final response
+ * or the maximum number of turns is reached. Supports middleware pipelines,
+ * event hooks, structured output, and streaming.
+ *
+ * Create instances via the fluent builder: Agent::build()->provider($p)->model('...')->create()
+ */
 final class Agent implements AgentInterface
 {
     /** @var array<string, ToolInterface> */
@@ -64,26 +74,34 @@ public function __construct(
 
     /**
      * Create a fluent builder for constructing an Agent.
+     *
+     * @return AgentBuilder A new builder instance
      */
     public static function build(): AgentBuilder
     {
         return new AgentBuilder();
     }
 
+    /** {@inheritDoc} */
     public function addTool(ToolInterface $tool): self
     {
         $this->tools[$tool->getName()] = $tool;
 
         return $this;
     }
 
+    /** {@inheritDoc} */
     public function getProvider(): ProviderInterface
     {
         return $this->provider;
     }
 
     /**
-     * Add middleware to the pipeline.
+     * Add middleware to the agent's request/response pipeline.
+     *
+     * @param MiddlewareInterface $middleware The middleware to add
+     *
+     * @return self For method chaining
      */
     public function addMiddleware(MiddlewareInterface $middleware): self
     {
@@ -93,14 +111,21 @@ public function addMiddleware(MiddlewareInterface $middleware): self
     }
 
     /**
-     * Run the agent with a prompt.
+     * Run the agent with a prompt, executing the full agentic loop.
+     *
+     * Sends the prompt through any middleware, then iterates: call the LLM,
+     * execute tool calls, feed results back, until a final response or max turns.
      *
      * @param string $prompt The user prompt
      * @param array{
      *     outputSchema?: Schema,
      *     context?: mixed,
      *     maxTurns?: int,
      * } $options Run options
+     *
+     * @return Response The final agent response
+     *
+     * @throws InvalidArgumentException If max turns is exceeded or structured output parsing fails
      */
     public function run(string $prompt, array $options = []): Response
     {
@@ -171,7 +196,9 @@ private function executeRun(string $prompt, array $options = []): Response
     }
 
     /**
-     * Stream the agent response as text chunks.
+     * {@inheritDoc}
+     *
+     * Streams text chunks from the provider without executing the agentic tool loop.
      */
     public function stream(string $prompt, array $options = []): iterable
     {
@@ -188,7 +215,9 @@ public function stream(string $prompt, array $options = []): iterable
     }
 
     /**
-     * Stream the agent response with detailed events.
+     * {@inheritDoc}
+     *
+     * Streams detailed events including text, tool calls, tool results, and completion.
      */
     public function streamEvents(string $prompt, array $options = []): iterable
     {

src/AgentBuilder.php

@@ -48,27 +48,55 @@ final class AgentBuilder
     /** @var array<MiddlewareInterface> */
     private array $middleware = [];
 
+    /**
+     * Set the LLM provider for the agent.
+     *
+     * @param ProviderInterface $provider The provider to use
+     *
+     * @return self For method chaining
+     */
     public function provider(ProviderInterface $provider): self
     {
         $this->provider = $provider;
 
         return $this;
     }
 
+    /**
+     * Set the model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514').
+     *
+     * @param string $model The model name
+     *
+     * @return self For method chaining
+     */
     public function model(string $model): self
     {
         $this->model = $model;
 
         return $this;
     }
 
+    /**
+     * Set the system instructions (system prompt) for the agent.
+     *
+     * @param string $instructions The system prompt text
+     *
+     * @return self For method chaining
+     */
     public function instructions(string $instructions): self
     {
         $this->instructions = $instructions;
 
         return $this;
     }
 
+    /**
+     * Add a single tool to the agent.
+     *
+     * @param ToolInterface $tool The tool to register
+     *
+     * @return self For method chaining
+     */
     public function tool(ToolInterface $tool): self
     {
         $this->tools[] = $tool;
@@ -77,7 +105,11 @@ public function tool(ToolInterface $tool): self
     }
 
     /**
-     * @param array<ToolInterface> $tools
+     * Add multiple tools to the agent at once.
+     *
+     * @param array<ToolInterface> $tools The tools to register
+     *
+     * @return self For method chaining
      */
     public function tools(array $tools): self
     {
@@ -86,34 +118,70 @@ public function tools(array $tools): self
         return $this;
     }
 
+    /**
+     * Register an event hook (e.g., 'beforeToolCall', 'afterToolCall', 'onError').
+     *
+     * @param string $name The hook name
+     * @param Closure $callback The callback to invoke when the hook fires
+     *
+     * @return self For method chaining
+     */
     public function hook(string $name, Closure $callback): self
     {
         $this->hooks[$name] = $callback;
 
         return $this;
     }
 
+    /**
+     * Set the maximum number of tokens the model can generate.
+     *
+     * @param int $maxTokens Maximum output tokens
+     *
+     * @return self For method chaining
+     */
     public function maxTokens(int $maxTokens): self
     {
         $this->maxTokens = $maxTokens;
 
         return $this;
     }
 
+    /**
+     * Set the sampling temperature (higher = more creative, lower = more deterministic).
+     *
+     * @param float $temperature Temperature value (typically 0.0 to 1.0)
+     *
+     * @return self For method chaining
+     */
     public function temperature(float $temperature): self
     {
         $this->temperature = $temperature;
 
         return $this;
     }
 
+    /**
+     * Set the maximum number of agentic turns (tool call loops) before stopping.
+     *
+     * @param int $maxTurns Maximum iterations of the agentic loop
+     *
+     * @return self For method chaining
+     */
     public function maxTurns(int $maxTurns): self
     {
         $this->maxTurns = $maxTurns;
 
         return $this;
     }
 
+    /**
+     * Add a single middleware to the pipeline.
+     *
+     * @param MiddlewareInterface $middleware The middleware to add
+     *
+     * @return self For method chaining
+     */
     public function addMiddleware(MiddlewareInterface $middleware): self
     {
         $this->middleware[] = $middleware;
@@ -122,7 +190,11 @@ public function addMiddleware(MiddlewareInterface $middleware): self
     }
 
     /**
-     * @param array<MiddlewareInterface> $middleware
+     * Add multiple middleware to the pipeline at once.
+     *
+     * @param array<MiddlewareInterface> $middleware The middleware to add
+     *
+     * @return self For method chaining
      */
     public function middleware(array $middleware): self
     {
@@ -131,6 +203,13 @@ public function middleware(array $middleware): self
         return $this;
     }
 
+    /**
+     * Build and return the configured Agent instance.
+     *
+     * @return Agent The fully configured agent
+     *
+     * @throws InvalidArgumentException If provider or model is not set
+     */
     public function create(): Agent
     {
         if ($this->provider === null) {

src/AgentJob.php

@@ -19,6 +19,12 @@
  */
 final class AgentJob
 {
+    /**
+     * @param string $agentClass Fully-qualified class name of the agent to run
+     * @param string $prompt The user prompt for the agent
+     * @param array<string, mixed> $options Agent run options
+     * @param string|null $callbackUrl Optional URL to POST results to when the job completes
+     */
     public function __construct(
         public readonly string $agentClass,
         public readonly string $prompt,
@@ -27,6 +33,11 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Serialize the job to an array for queue transport.
+     *
+     * @return array{agentClass: string, prompt: string, options: array, callbackUrl: string|null}
+     */
     public function toArray(): array
     {
         return [
@@ -37,6 +48,13 @@ public function toArray(): array
         ];
     }
 
+    /**
+     * Deserialize a job from a queue-transported array.
+     *
+     * @param array{agentClass: string, prompt: string, options?: array, callbackUrl?: string|null} $data Serialised job data
+     *
+     * @return self The restored job
+     */
     public static function fromArray(array $data): self
     {
         return new self(

src/AgentRequest.php

@@ -19,6 +19,12 @@
  */
 final class AgentRequest
 {
+    /**
+     * @param string $prompt The user prompt
+     * @param array<string, mixed> $options Agent run options (e.g., outputSchema, maxTurns)
+     * @param array<Message> $messages Pre-existing conversation messages
+     * @param array<string, mixed> $metadata Arbitrary metadata for middleware inspection
+     */
     public function __construct(
         public readonly string $prompt,
         public readonly array $options = [],
@@ -27,6 +33,14 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Return a new request with an additional option set.
+     *
+     * @param string $key Option key
+     * @param mixed $value Option value
+     *
+     * @return self A new immutable request with the option merged
+     */
     public function withOption(string $key, mixed $value): self
     {
         return new self(
@@ -37,6 +51,13 @@ public function withOption(string $key, mixed $value): self
         );
     }
 
+    /**
+     * Return a new request with the message history replaced.
+     *
+     * @param array<Message> $messages The new message list
+     *
+     * @return self A new immutable request with the updated messages
+     */
     public function withMessages(array $messages): self
     {
         return new self(
@@ -47,6 +68,14 @@ public function withMessages(array $messages): self
         );
     }
 
+    /**
+     * Return a new request with an additional metadata entry.
+     *
+     * @param string $key Metadata key
+     * @param mixed $value Metadata value
+     *
+     * @return self A new immutable request with the metadata merged
+     */
     public function withMetadata(string $key, mixed $value): self
     {
         return new self(

src/Attributes/Description.php

@@ -16,9 +16,18 @@
 
 use Attribute;
 
+/**
+ * Provides a description for a tool parameter or property in the generated JSON schema.
+ *
+ * Applied to method parameters alongside the #[Tool] attribute so the LLM
+ * understands what each parameter represents.
+ */
 #[Attribute(Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY)]
 class Description
 {
+    /**
+     * @param string $text Human-readable description of the parameter
+     */
     public function __construct(
         public readonly string $text,
     ) {