> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V1.12.0

# Release Notes - v1.12.0

## Executive Summary

The release includes substantial refactoring across core packages to improve separation of concerns, eliminate technical debt, and achieve better performance characteristics.

## Breaking Changes

### instructor Package

* **Removed `CanExecuteStructuredOutput` interface** - Replaced with dual-interface architecture: `CanStreamStructuredOutputUpdates` (stream-level iteration) and `CanHandleStructuredOutputAttempts` (attempt-level orchestration)
* **Removed `IterativeToGeneratorAdapter`** - All execution now flows through unified `AttemptIterator` with specialized stream iterators
* **Request handler hierarchy replaced** - `RequestHandler`, `SyncRequestHandler`, `PartialStreamingRequestHandler` removed in favor of stream iterator pattern

### addons Package

* **Namespace reorganization** - Shared components moved from `StepByStep` to domain-specific namespaces:
  * Chat traits moved to `Chat/State` and `Chat/Step` namespaces
  * Selector implementations moved to dedicated subdirectories

### polyglot Package

* **Default HTTP client changed** - Changed from `guzzle` to `curl` preset to make it easy to use Instructor out of the box

### utils Package

* **`ProgrammingLanguage` is now an enum** - Changed from class to `enum ProgrammingLanguage : string`; direct instantiation patterns will break

## New Features

### Native cURL HTTP Driver (http-client)

Zero-dependency HTTP functionality using PHP's built-in cURL:

* **CurlDriver**: Full HTTP method support with custom headers, timeouts, SSL verification
* **Concurrent requests**: `CurlPool` using `curl_multi` for parallel execution
* **Streaming support**: `CurlStreamingHttpResponse` with real-time chunked delivery
* **Event integration**: Full support for `HttpRequestSent`, `HttpResponseReceived`, `HttpRequestFailed`
* **Comprehensive tests**: Integration tests covering GET/POST, headers, errors, timeouts, streaming

## Major Improvements

### Unified Streaming Architecture (instructor)

Code refactoring achieving O(1) memory usage and consistent execution model:

* **Stream iterator pattern**: Three specialized implementations (`SyncUpdateGenerator`, `PartialStreamingUpdateGenerator`, `StreamingUpdatesGenerator`) with unified contract
* **AttemptIterator orchestration**: Single code path for sync and streaming with validation, retries, failure recovery
* **Transducer-based pipeline**: Pure transformation stages (delta extraction, JSON assembly, deserialization, deduplication, sequence tracking) using immutable state
* **Rolling aggregation**: Eliminated accumulation of all partial responses
* **Robust retry handling**: `DefaultRetryPolicy` with flexible logic for validation failures, connection errors, rate limits
* **Enhanced state management**: `StructuredOutputAttemptState` and `AttemptPhase` enum for explicit progress tracking

### ToolUse Refactoring (addons)

Significant architectural improvements with better separation of concerns:

* **ReAct driver decomposition**: Extracted into action classes (`MakeReActPrompt`, `MakeToolCalls`) and validation layer (`ReActValidator`)
* **Improved data structures**: `DecisionWithDetails`, `ReActDecision` implementing `Decision` contract
* **Better error handling**: Structured validation results with comprehensive decision validation
* **Formatter extraction**: `ReActFormatter` utility for output formatting
* **Reorganized continuation**: Moved to `ContinuationCriteria` subdirectory
* **Executor abstraction**: `CanExecuteToolCalls` contract

### Chat Improvements (addons)

Enhanced code organization and reusability:

* **Extracted traits**: `HandlesChatSteps`, `HandlesChatCompletion`, `HasChatCompletion` for state and step management
* **Reorganized selectors**: Moved to dedicated namespaces (`RoundRobin`, `LLMSelector`)
* **Enhanced state management**: Dedicated step handling

## New LLM Provider Support

### Inception Inference Provider (polyglot)

* **InceptionDriver**: Complete inference driver supporting Inception API

## Bug Fixes & Quality Improvements

### Stream Completion Handling (stream)

* **Fixed completion phase**: Added `transduction->completed()` call to flush remaining values
* **Stateful transformations**: Properly finalize and emit accumulated data at stream end
* **Data loss prevention**: Ensures buffered data is not lost on stream termination

### Type Safety Improvements (utils)

* **PartialJsonParser**: Enhanced type safety ensuring `parse()` always returns `array|object` as declared
* **Metadata**: Added `withMergedData(array $data)` method for batch updates

### Static Analysis (addons)

* **Fixed Psalm/PHPStan issues**: Resolved static analysis warnings throughout
* **Improved transducer stability**: Enhanced streaming driver reliability
* **Better error handling**: Comprehensive error handling in ReActDriver

## Migration Guide

### For `instructor` Users

* No action required for public API users - changes are internal
* Custom implementations of `CanExecuteStructuredOutput` must migrate to new dual-interface architecture
* Streaming behavior is now more consistent with better memory efficiency

### For `polyglot` Users

* Verify HTTP behavior if relying on Guzzle-specific features
* Update configuration to explicitly specify `guzzle` preset if needed: `'preset' => 'guzzle'`

### For `utils` Users

* Update `ProgrammingLanguage` usage from class to enum syntax
* Example: `ProgrammingLanguage::PHP` instead of `new ProgrammingLanguage('PHP')`
* Consider SafeSandbox for any untrusted code execution needs