Skip to main content

​
What’s New

v2.0 is a ground-up rework focused on performance, type safety, and a tighter API surface.
  • Faster, leaner — streaming is more memory efficient, execution is lazy by default, and internal code paths have been consolidated.
  • Tighter APIs — both Instructor and Polyglot have cleaner, more type-safe public APIs with explicit fields instead of mode-based configuration.
  • More reliable — extensive unit, feature, integration tests and benchmarks back this release. A substantial number of bugs have been fixed across the stack.
  • Agent building blocks — new cognesy/agents package for custom agents, and an expanded cognesy/agent-ctrl to interact with CLI coding agents from PHP.

​
Breaking Changes

  • Instructor’s public API centers on StructuredOutput, StructuredOutputRuntime, PendingStructuredOutput, StructuredOutputResponse, and StructuredOutputStream.
  • Polyglot uses explicit LLM API fields (responseFormat, tools, toolChoice) instead of output modes. Streaming moves to stream()->deltas().

​
Instructor

  • Execution flows through StructuredOutputRuntime, with lazy execution via PendingStructuredOutput.
  • Streaming is Instructor-owned: StructuredOutputStream exposes responses(), partials(), and sequence(). StructuredOutputStreamState accumulates state internally.
  • Configuration, validation, transformation, deserialization, and extraction are explicit parts of the runtime rather than scattered across older code paths.

​
Polyglot

  • InferenceRuntime and EmbeddingsRuntime sit behind the Inference and Embeddings facades.
  • New inference drivers: openai-responses, openresponses, glm, qwen.
  • Built-in pricing via Pricing\Cost, per-model pricing objects, and cost calculators.
  • Polyglot handles raw transport — structured value ownership belongs to Instructor.

​
Agents (cognesy/agents)

New package. Building blocks for custom agents: AgentLoop, AgentBuilder, hooks, guards, templates, subagents, skills, and SessionRuntime for persisted workflows. Compose agents from capabilities like bash, file tools, structured outputs, summarization, self-critique, planning, execution history, and broadcasting. Two built-in drivers: ToolCallingDriver (native tool-calling APIs) and ReActDriver (Thought/Action/Observation loops).

​
AgentCtrl (cognesy/agent-ctrl)

Unified PHP API for interacting with CLI coding agents — Claude Code, Codex, OpenCode, Pi (new), and Gemini (new).
  • AgentCtrl::make() and dedicated builders (::codex(), ::openCode(), ::pi(), ::gemini()) return normalized AgentResponse objects.
  • Streaming callbacks, session resume/continue, typed IDs (AgentSessionId, AgentToolCallId), and AgentCtrlConsoleLogger for observability.

​
Migrating from v1.x

  • Instructor: use ->get(), ->response(), and ->stream(). For partial snapshots, switch to stream()->responses(), stream()->partials(), or stream()->sequence().
  • Polyglot: replace mode-based JSON/tool config with responseFormat, tools, toolChoice, and delta-based streaming.
  • See packages/instructor/docs/upgrade.md and packages/polyglot/docs/upgrade.md for details.