wip

Author: tymondesigns

src/Agents/Agent.php

@@ -73,7 +73,10 @@ public function __construct(
 
         $this->memory = new ChatMemory(new InMemoryStore($this->prompt->messages->withoutPlaceholders()));
         $this->usage = Usage::empty();
-        $this->llm = Utils::toLLM($llm);
+
+        $this->llm = $llm !== null
+            ? Utils::toLLM($llm)
+            : $this->prompt->metadata?->toLLM() ?? Utils::toLLM($llm);
 
         if ($this->tools !== []) {
             $this->llm->withTools($this->tools, $this->toolChoice);

src/LLM/AbstractLLM.php

@@ -80,6 +80,8 @@ abstract class AbstractLLM implements LLM
 
     protected bool $ignoreModelFeatures = false;
 
+    protected bool $includeRaw = false;
+
     public function __construct(
         protected string $model,
         protected ModelProvider $modelProvider,
@@ -414,6 +416,16 @@ public function shouldParseOutput(bool $shouldParseOutput = true): static
         return $this;
     }
 
+    /**
+     * Set whether the raw provider response should be included in the result.
+     */
+    public function includeRaw(bool $includeRaw = true): static
+    {
+        $this->includeRaw = $includeRaw;
+
+        return $this;
+    }
+
     protected function applyOutputParserIfApplicable(
         ChatGeneration|ChatGenerationChunk $generationOrChunk,
     ): ChatGeneration|ChatGenerationChunk {

src/LLM/Data/ChatGenerationChunk.php

@@ -15,6 +15,9 @@
  */
 readonly class ChatGenerationChunk implements Arrayable
 {
+    /**
+     * @param array<string, mixed>|null $rawChunk
+     */
     public function __construct(
         public string $id,
         public AssistantMessage $message,
@@ -26,6 +29,7 @@ public function __construct(
         public bool $isFinal = false,
         public mixed $parsedOutput = null,
         public ?string $outputParserError = null,
+        public ?array $rawChunk = null,
     ) {}
 
     public function cloneWithParsedOutput(mixed $parsedOutput): self
@@ -57,6 +61,7 @@ public function toArray(): array
             'parsed_output' => $this->parsedOutput,
             'output_parser_error' => $this->outputParserError,
             'created_at' => $this->createdAt,
+            'raw_chunk' => $this->rawChunk,
         ];
     }
 }

src/LLM/Data/ChatResult.php

@@ -14,12 +14,12 @@
     public mixed $parsedOutput;
 
     /**
-     * @param array<int, mixed> $rawResponse
+     * @param array<int, mixed>|null $rawResponse
      */
     public function __construct(
         public ChatGeneration $generation,
         public Usage $usage,
-        public array $rawResponse = [],
+        public ?array $rawResponse = null,
     ) {
         $this->parsedOutput = $this->generation->parsedOutput;
     }
@@ -38,6 +38,7 @@ public function toArray(): array
         return [
             'generation' => $this->generation,
             'usage' => $this->usage,
+            'raw_response' => $this->rawResponse,
         ];
     }
 }

src/LLM/Drivers/OpenAI/Chat/Concerns/MapsResponse.php

@@ -47,10 +47,15 @@ protected function mapResponse(CreateResponse $response): ChatResult
 
         $generation = $this->applyOutputParserIfApplicable($generation);
 
+        /** @var array<string, mixed>|null $rawResponse */
+        $rawResponse = $this->includeRaw
+            ? $response->toArray()
+            : null;
+
         return new ChatResult(
             $generation,
             $usage,
-            $response->toArray(), // @phpstan-ignore argument.type
+            $rawResponse, // @phpstan-ignore argument.type
         );
     }
 }

src/LLM/Drivers/OpenAI/Chat/Concerns/MapsStreamResponse.php

@@ -155,7 +155,8 @@ protected function mapStreamResponse(StreamResponse $response): ChatStreamResult
                     finishReason: $finishReason,
                     usage: $usage,
                     contentSoFar: $contentSoFar,
-                    isFinal: $isLastContentChunk,
+                    isFinal: $isLastContentChunk && $usage !== null,
+                    rawChunk: $this->includeRaw ? $chunk->toArray() : null,
                 );
 
                 $chatGenerationChunk = $this->applyOutputParserIfApplicable($chatGenerationChunk);

src/LLM/Drivers/OpenAI/Responses/Concerns/MapsResponse.php

@@ -94,8 +94,10 @@ protected function mapResponse(CreateResponse $response): ChatResult
 
         $generation = $this->applyOutputParserIfApplicable($generation);
 
-        /** @var array<string, mixed> $rawResponse */
-        $rawResponse = $response->toArray();
+        /** @var array<string, mixed>|null $rawResponse */
+        $rawResponse = $this->includeRaw
+            ? $response->toArray()
+            : null;
 
         return new ChatResult(
             $generation,

src/LLM/Drivers/OpenAI/Responses/Concerns/MapsStreamResponse.php

@@ -176,6 +176,11 @@ protected function mapStreamResponse(StreamResponse $response): ChatStreamResult
                 // Determine chunk type
                 $chunkType = $this->resolveResponsesChunkType($event, $currentDelta, $contentSoFar, $finishReason);
 
+                /** @var array<string, mixed>|null $rawChunk */
+                $rawChunk = $this->includeRaw
+                    ? $streamChunk->toArray()
+                    : null;
+
                 $chatGenerationChunk = new ChatGenerationChunk(
                     id: $responseId ?? 'unknown',
                     message: new AssistantMessage(
@@ -198,6 +203,7 @@ protected function mapStreamResponse(StreamResponse $response): ChatStreamResult
                     usage: $responseUsage,
                     contentSoFar: $contentSoFar,
                     isFinal: $isFinal,
+                    rawChunk: $rawChunk,
                 );
 
                 $chatGenerationChunk = $this->applyOutputParserIfApplicable($chatGenerationChunk);

src/LLM/Drivers/OpenAI/Responses/Concerns/MapsUsage.php

@@ -22,8 +22,8 @@ protected function mapUsage(?CreateResponseUsage $usage): ?Usage
         return new Usage(
             promptTokens: $usage->inputTokens,
             completionTokens: $usage->outputTokens,
-            cachedTokens: $usage->inputTokensDetails?->cachedTokens,
-            reasoningTokens: $usage->outputTokensDetails?->reasoningTokens,
+            cachedTokens: $usage->inputTokensDetails->cachedTokens,
+            reasoningTokens: $usage->outputTokensDetails->reasoningTokens,
             totalTokens: $usage->totalTokens,
             inputCost: $this->modelProvider->inputCostForTokens($this->model, $usage->inputTokens),
             outputCost: $this->modelProvider->outputCostForTokens($this->model, $usage->outputTokens),

src/Prompts/Builders/Concerns/BuildsPrompts.php

@@ -40,6 +40,8 @@ public function initialVariables(array $initialVariables): self
     }
 
     /**
+     * Define the metadata for the prompt.
+     *
      * @param array<string, mixed> $parameters
      * @param array<int, \Cortex\LLM\Contracts\Tool|\Closure|string> $tools
      * @param array<string, mixed> $additional