Skip to main content

​
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