refactor(polyglot,instructor): clean attempt lifecycle

Author: ddebowczyk

.beads/issues.jsonl

@@ -4,7 +4,7 @@
 
 - Prevent null dereference when finalizing streaming responses with no current attempt
   - packages/polyglot/src/Inference/Data/InferenceExecution.php
-    - Null-safe access to `currentAttempt` in `withFinalizedPartialResponse()` and `withFailedFinalizedResponse()`
+    - Null-safe access to `currentAttempt` in `withFinalizedPartialResponse()` and `withFailedAttempt()`
   - packages/polyglot/src/Inference/Data/InferenceAttempt.php
     - Null-safe `withFinalizedPartialResponse()` using empty `PartialInferenceResponseList` when needed
 
@@ -36,4 +36,3 @@
 - This release focuses on correctness and immutability:
   - Eliminates potential fatals in streaming finalization and console display
   - Standardizes usage accumulation to immutable patterns across modules
-

docs/release-notes/v1.9.1.mdx

@@ -186,6 +186,10 @@ public function useObjectReferences(): bool {
         return $this->useObjectReferences;
     }
 
+    /**
+     * Maximum number of retries after the first attempt.
+     * Total attempts allowed = maxRetries + 1.
+     */
     public function maxRetries(): int {
         return $this->maxRetries;
     }

packages/instructor/src/Config/StructuredOutputConfig.php

@@ -133,16 +133,18 @@ public function withToolDescription(string $toolDescription) : static {
     }
 
     /** @param array<string, mixed> $values */
-    public function setPropertyValues(array $values) : void {
+    public function withPropertyValues(array $values) : static {
         if (!is_object($this->instance)) {
-            return;
+            return $this;
         }
+        $instance = clone $this->instance;
         foreach ($values as $name => $value) {
-            if (property_exists($this->instance, $name)) {
+            if (property_exists($instance, $name)) {
                 /** @phpstan-ignore-next-line */
-                $this->instance->$name = $value;
+                $instance->$name = $value;
             }
         }
+        return $this->with(instance: $instance);
     }
 
     // CONVERSION //////////////////////////////////////////////////////
@@ -200,7 +202,7 @@ public function toolChoice() : string|array {
     public function toArray() : array {
         return [
             'class' => $this->class,
-            'instance' => get_object_vars($this->instance),
+            'instance' => is_object($this->instance) ? get_object_vars($this->instance) : [],
             'schema' => $this->schema->toArray(),
             'jsonSchema' => $this->jsonSchema,
             'schemaName' => $this->schemaName,

packages/instructor/src/Data/ResponseModel.php

@@ -130,7 +130,11 @@ public static function defaultStreamingExtractors(): array
     public function extract(InferenceResponse $response, OutputMode $mode): Result
     {
         // 1. DATA ACCESS: Get content string based on mode (uniform for all modes)
-        $content = $this->getContentString($response, $mode);
+        $contentResult = $this->getContentString($response, $mode);
+        if ($contentResult->isFailure()) {
+            return Result::failure($contentResult->error());
+        }
+        $content = $contentResult->unwrap();
 
         if (empty($content)) {
             return Result::failure('Empty response content');
@@ -169,31 +173,36 @@ public function extractors(): array
     /**
      * Uniform data access - no special cases, just different sources.
      */
-    private function getContentString(InferenceResponse $response, OutputMode $mode): string
+    /**
+     * @return Result<string, Throwable>
+     */
+    private function getContentString(InferenceResponse $response, OutputMode $mode): Result
     {
         return match ($mode) {
             OutputMode::Tools => $this->getToolCallContent($response),
-            default => $response->content(),
+            default => Result::success($response->content()),
         };
     }
 
     /**
      * Get content from tool calls as JSON string.
+     *
+     * @return Result<string, Throwable>
      */
-    private function getToolCallContent(InferenceResponse $response): string
+    private function getToolCallContent(InferenceResponse $response): Result
     {
         $toolCalls = $response->toolCalls();
 
         if ($toolCalls->isEmpty()) {
             // Fallback for providers that return tool-call JSON in content.
-            return $response->content();
+            return Result::success($response->content());
         }
 
         if ($toolCalls->hasSingle()) {
-            return json_encode($toolCalls->first()?->args() ?? [], JSON_THROW_ON_ERROR);
+            return Result::try(fn() => json_encode($toolCalls->first()?->args() ?? [], JSON_THROW_ON_ERROR));
         }
 
-        return json_encode($toolCalls->toArray(), JSON_THROW_ON_ERROR);
+        return Result::try(fn() => json_encode($toolCalls->toArray(), JSON_THROW_ON_ERROR));
     }
 
     /**

packages/instructor/src/Extraction/ResponseExtractor.php

@@ -121,9 +121,9 @@ public function withHttpClient(HttpClient $httpClient): static {
         return $this;
     }
 
-    public function withHttpClientPreset(string $string): static {
+    public function withHttpClientPreset(string $preset): static {
         $builder = new HttpClientBuilder(events: $this->events);
-        $this->httpClient = $builder->withPreset($string)->create();
+        $this->httpClient = $builder->withPreset($preset)->create();
         return $this;
     }
 
@@ -132,7 +132,7 @@ public function withDebugPreset(string $preset): static {
         return $this;
     }
 
-    public function withClientInstance(string $driverName, object $clientInstance): self {
+    public function withClientInstance(string $driverName, object $clientInstance): static {
         $builder = new HttpClientBuilder(events: $this->events);
         $this->httpClient = $builder->withClientInstance(
             driverName: $driverName,
@@ -222,7 +222,7 @@ public function withCachedContext(
         string $system = '',
         string $prompt = '',
         array $examples = [],
-    ): ?self {
+    ): static {
         $this->requestBuilder->withCachedContext($messages, $system, $prompt, $examples);
         return $this;
     }

packages/instructor/src/StructuredOutput.php

@@ -35,6 +35,7 @@ class StructuredOutputStream
     private StructuredOutputExecution $execution;
     private InferenceResponse|null $lastResponse = null;
     private ResponseCachePolicy $cachePolicy;
+    private bool $started = false;
 
     /**
      * @param Generator<StructuredOutputExecution> $stream
@@ -141,9 +142,8 @@ public function finalValue() : mixed {
      * Processes response stream and returns only the final response.
      */
     public function finalResponse() : InferenceResponse {
-        foreach ($this->streamResponses() as $partialResponse) {
+        foreach ($this->streamResponses() as $_) {
             // Just consume the stream, processStream() handles the updates
-            $tmp = $partialResponse;
         }
         if (is_null($this->lastResponse)) {
             throw new RuntimeException('Expected final InferenceResponse, got null');
@@ -153,8 +153,8 @@ public function finalResponse() : InferenceResponse {
 
     /**
      * Returns raw stream for custom processing.
-     * Processing with this method does not trigger any events or dispatch any notifications.
-     * It also does not update usage data on the stream object.
+     * StructuredOutputStarted may have already been dispatched when the stream was created.
+     * Processing with this method does not emit response update events or usage updates.
      *
      * @return Generator<StructuredOutputExecution>
      */
@@ -200,7 +200,10 @@ private function streamResponses(): Generator {
      * @return Generator<StructuredOutputExecution> A generator yielding structured output execution updates.
      */
     private function getStream(StructuredOutputExecution $execution) : Generator {
-        $this->events->dispatch(new StructuredOutputStarted(['request' => $execution->request()->toArray()]));
+        if (!$this->started) {
+            $this->events->dispatch(new StructuredOutputStarted(['request' => $execution->request()->toArray()]));
+            $this->started = true;
+        }
 
         return match($this->shouldCache()) {
             false => $this->streamWithoutCaching($execution),

packages/instructor/src/StructuredOutputStream.php

@@ -72,8 +72,14 @@ protected function validateObject(object $response) : ValidationResult {
                 $validator instanceof CanValidateObject => $validator,
                 default => throw new Exception('Validator must implement CanValidateObject interface'),
             };
-            // TODO: how do we handle exceptions here?
-            $results[] = $validator->validate($response);
+            try {
+                $results[] = $validator->validate($response);
+            } catch (\Throwable $error) {
+                $results[] = ValidationResult::invalid(
+                    new ValidationError(field: 'exception', value: null, message: $error->getMessage()),
+                    'Validator threw an exception',
+                );
+            }
         }
         return ValidationResult::merge($results);
     }

packages/instructor/src/Validation/ResponseValidator.php

@@ -23,14 +23,15 @@ static public function valid(): ValidationResult {
         return new ValidationResult();
     }
 
-    static public function invalid(string|array $errors, string $message = ''): ValidationResult {
-        if (is_string($errors)) {
-            $errors = [$errors];
-        }
-        if (count($errors) === 0) {
+    /**
+     * @param ValidationError|ValidationError[] $errors
+     */
+    static public function invalid(ValidationError|array $errors, string $message = ''): ValidationResult {
+        $normalized = self::normalizeErrors($errors);
+        if (count($normalized) === 0) {
             throw new \InvalidArgumentException('Errors must be provided when creating an invalid ValidationResult');
         }
-        return new ValidationResult($errors, $message);
+        return new ValidationResult($normalized, $message);
     }
 
     static public function make(array $errors = [], string $message = ''): ValidationResult {
@@ -57,6 +58,18 @@ static public function merge(array $validationResults, string $message = ''): Va
         };
     }
 
+    /**
+     * @param ValidationError|ValidationError[] $errors
+     * @return ValidationError[]
+     */
+    private static function normalizeErrors(ValidationError|array $errors): array {
+        $list = $errors instanceof ValidationError ? [$errors] : $errors;
+        return array_values(array_filter(
+            $list,
+            fn (mixed $error): bool => $error instanceof ValidationError
+        ));
+    }
+
     /// CONVENIENCE METHODS //////////////////////////////////////////////////////////////////
 
     public function isValid(): bool {
@@ -89,4 +102,4 @@ public function toArray(): array {
             'message' => $this->message,
         ];
     }
-}
+}

packages/instructor/src/Validation/ValidationResult.php

@@ -4,6 +4,7 @@
 
 use Cognesy\Instructor\Validation\Contracts\CanValidateObject;
 use Cognesy\Instructor\Validation\Contracts\CanValidateSelf;
+use Cognesy\Instructor\Validation\ValidationError;
 use Cognesy\Instructor\Validation\ValidationResult;
 
 class SelfValidator implements CanValidateObject
@@ -14,8 +15,12 @@ public function validate(object $dataObject): ValidationResult {
             return $dataObject->validate();
         }
         return ValidationResult::invalid(
-            ['Object does not implement CanValidateSelf interface'],
+            new ValidationError(
+                field: 'object',
+                value: $dataObject,
+                message: 'Object does not implement CanValidateSelf interface',
+            ),
             'Validation failed',
         );
     }
-}
+}