> ## 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.

# V2.0.0

## 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.