V2.5.0

​

Cleaner Structured-Output Contract

$schema = [
    'type' => 'object',
    'properties' => [
        'status' => [
            'type' => 'string',
            'enum' => ['open', 'closed'],
        ],
    ],
    'required' => ['status'],
];

$result = $structuredOutput
    ->with(messages: 'The issue is open.', responseModel: $schema)
    ->get();

// ['status' => 'open']

​

Validation and Materialization

• Array, class, stdClass, and self-deserializing targets share schema validation.
• Completed streaming and synchronous extraction use the same final materialization path.
• Configured and self transformations run exactly once.
• Transformation failures fail the attempt and may retry instead of returning unchanged data.
• Nested Dynamic hydration failures report their field or index path.

​

Public API

• Added intoStdClass().
• Added intoSelfDeserializing(); intoObject() remains as a deprecated compatibility alias.
• Removed the unused outputClass / withDefaultOutputClass() configuration surface.
• Deprecated global defaultToStdClass; use per-request intoStdClass() instead.
• Existing PendingStructuredOutput::toJsonObject(), toJson(), and toArray() remain concise raw-response inspection methods. get() and typed get*() methods return the final structured result.
• Typed result mismatches now throw UnexpectedStructuredOutputTypeException and include the concrete actual type.
• Requests containing a live self-deserializing target fail explicitly when serialized or restored; Instructor no longer fabricates uninitialized target instances with reflection.

​

Events

• Cognesy\Instructor\Events\Response\ResponseMaterialized
• Cognesy\Instructor\Events\Response\ResponseMaterializationFailed
• Cognesy\Instructor\Events\Attempt\ResponseRetryScheduled
• Cognesy\Instructor\Events\Attempt\ResponseRecoveryExhausted

​

Prompts and Dependencies

​

Package Highlights

• Schema: added the shared SchemaDataValidator for required and nullable fields, primitive types, nested objects and collections, and scalar or backed-enum values.
• Dynamic: Structure now delegates validation to the shared validator and no longer exposes the removed transform() or no-op withValidation() methods.
• Laravel: published extraction configuration now uses retry_prompt_class; the inline retry_prompt key remains only as deprecated legacy compatibility until 2.6.
• Symfony: removed the unused output_class / outputClass configuration keys.
• Events: removed class-alias canonicalization after the deprecated event namespace aliases were deleted.
• Addons: function-call argument schemas no longer leak root x-php-class hydration metadata into tool definitions.
• Agents: added UseCodingTools with bounded read, bash, edit, and write tools; file operations now stream bounded data and edits commit through a temporary file instead of loading and rewriting unbounded content.
• Sandbox: host execution now uses the bounded ProcRunner, retains stream tails after capture limits, and reports command-start failures with a stable exit code.

​

Upgrade Notes

1. Remove Structure checks and toArray() calls around plain JSON Schema results; get() now returns the associative array directly.
2. If you pass a Dynamic Structure intentionally, expect get() to return that Structure; call toArray() explicitly when conversion is wanted.
3. Use x-php-class or intoInstanceOf() for class hydration, intoStdClass() for stdClass, and intoArray() to override a class-backed schema.
4. Correct or remove unknown root x-php-class metadata before execution.
5. Replace intoObject() with intoSelfDeserializing(). Replace global defaultToStdClass with per-request intoStdClass().
6. Remove outputClass, output_class, and withDefaultOutputClass() configuration. Remove throwOnTransformationFailure; transformation failures now always fail the attempt.
7. Update event listener imports to the canonical namespaces listed above and migrate removed recovery/materialization events to the new result-neutral events.
8. Replace inline modePrompts, retryPrompt, and chatStructure customization with prompt classes. The legacy values work only with an explicitly injected deprecated RequestMaterializer in 2.5 and are scheduled for removal in 2.6.
9. If your application imports Cognesy\Dynamic directly, add the dependency explicitly:
   composer require cognesy/instructor-dynamic:^2.5
   
10. Expect schema, deserialization, object-validation, and transformation failures to fail the attempt and enter the configured retry policy rather than returning a partially materialized or unchanged value.
11. Remove calls to Dynamic Structure::transform() and the no-op Structure::withValidation() compatibility method; call toArray() only when an explicit Structure-to-array conversion is required.