Instructor for PHP

POWERED BY

FOUR PACKAGES, ONE ECOSYSTEM

Each package solves a distinct problem. Use one or combine them. They share the same design principles and work together seamlessly.

Polyglot

Unified LLM API

One API for 25+ providers: OpenAI, Anthropic, Gemini, Groq, Ollama, and more
Inference and embeddings through the same fluent interface
Streaming with deltas, filtering, and mapping
YAML preset system for easy provider switching

$text = Inference::using('openai')
    ->withMessages('Say hello.')
    ->get();

Polyglot docs

Instructor

Structured Outputs

Extract typed PHP objects from LLM responses automatically
Automatic validation with configurable retry policies
Sync and streaming with partial object updates
Multiple output modes: JSON, Tool calling, Markdown+JSON

$person = StructuredOutput::using('openai')
    ->with(
        messages: 'Jason is 28.',
        responseModel: Person::class,
    )->get();

Instructor docs

Agents

Agent SDK

Composable agent loop with immutable state
Pluggable drivers: ToolCalling, ReAct, Fake for testing
Lifecycle hooks, tools, subagents, and capability packs
Session persistence across HTTP requests

$loop = AgentBuilder::base()
    ->withCapability(new UseBash())
    ->withCapability(new UseGuards(maxSteps: 10))
    ->build();

Agents docs

AgentCtrl

Coding Agent Control

Orchestrate Claude Code, Codex, OpenCode, Pi, and Gemini
Blocking execution or real-time streaming with callbacks
Session continuity and sandbox control
Normalized responses: text, usage, cost, tool calls

$response = AgentCtrl::claudeCode()
    ->inDirectory('/my/project')
    ->execute('Summarize this repo.');
echo $response->text();

AgentCtrl docs

HOW IT FITS TOGETHER

Four packages, clear boundaries. Polyglot handles all LLM communication. Instructor and Agents build on top of it. AgentCtrl talks directly to external coding agent CLIs.

Your PHP Application

Instructor

Structured Outputs

Polyglot

Unified LLM API

25+ LLM Providers

OpenAI, Anthropic, Gemini, ...

Agents

Agent SDK

Polyglot

Inference + Embeddings

25+ LLM Providers

Groq, Ollama, Mistral, ...

AgentCtrl

Coding Agent Control

CLI Code Agents

Claude Code, Codex, OpenCode, Pi, Gemini

Instructor

Structured Outputs

Polyglot

Unified LLM API

25+ LLM Providers

OpenAI, Anthropic, Gemini, ...

Agents

Agent SDK

Polyglot

Inference + Embeddings

25+ LLM Providers

Groq, Ollama, Mistral, ...

AgentCtrl

Coding Agent Control

CLI Code Agents

Claude Code, Codex, OpenCode, Pi, Gemini

GET STARTED IN 3 STEPS

1

Install with Composer

$ composer require cognesy/instructor-php

2

Set your API key

$ export OPENAI_API_KEY=sk-...

3

Pick the capability you need

Start with one, add more as your application grows.

Unified LLM API

Call 25+ providers through one request API.

docs

1use Cognesy\Polyglot\Inference\Inference;
2 
3$text = Inference::using('openai')
4    ->withSystem('You are a senior PHP developer.')
5    ->withMessages('Explain the strategy pattern in one paragraph.')
6    ->get();

Structured outputs

Get typed PHP objects or plain arrays from model responses.

docs

 1use Cognesy\Instructor\StructuredOutput;
 2 
 3final class Person {
 4    public string $name;
 5    public int $age;
 6}
 7 
 8$person = StructuredOutput::using('openai')
 9    ->withSystem('Extract person data from the text.')
10    ->with(
11        messages: 'Jason is 28 years old.',
12        responseModel: Person::class,
13    )
14    ->get();

Agents

Build agents with context, tools, stop rules, and sessions.

docs

1use Cognesy\Agents\AgentLoop;
2use Cognesy\Agents\Data\AgentState;
3 
4$state = AgentState::empty()
5    ->withSystemPrompt('You are a math tutor. Show your work.')
6    ->withUserMessage('What is 12 * 15?');
7 
8$result = AgentLoop::default()->execute($state);
9echo $result->finalResponse()->toString();

Coding agent control

Control Codex, Claude Code, and OpenCode from PHP.

docs

1use Cognesy\AgentCtrl\AgentCtrl;
2 
3$response = AgentCtrl::claudeCode()
4    ->withSystemPrompt('Focus on architecture, skip implementation details.')
5    ->inDirectory(__DIR__)
6    ->execute('Summarize this repository.');
7 
8echo $response->text();

WHY INSTRUCTORPHP

Built for PHP developers who want AI capabilities without leaving their ecosystem.

Framework-agnostic

Works with plain PHP, Laravel, Symfony, or your own structure. No framework lock-in.

Type-safe

Leverages PHP's type system. Get typed objects from LLMs, not unstructured strings you have to parse.

Composable

Each package works independently. Use only what you need. Add more when your application grows.

Testable

FakeAgentDriver for deterministic testing. No API calls needed. Script scenarios and verify behavior.

Production-ready

Retry policies, validation, error handling, and observability built in. Not a prototype toolkit.

PHP-native

Not a port from Python or JavaScript. Designed for PHP idioms, patterns, and developer expectations.

SUPPORTED PROVIDERS

Write your code once. Switch providers by changing a single string. No rewrites needed.

LLM Inference

via Polyglot

OpenAI Anthropic Gemini Azure OpenAI AWS Bedrock Groq Mistral Cohere Deepseek Fireworks Ollama Together OpenRouter Perplexity xAI Cerebras SambaNova Hugging Face Qwen MiniMax Moonshot GLM A21 Inception Meta

Embeddings

via Polyglot

OpenAI Azure Gemini Cohere Jina Ollama

Coding Agents

via AgentCtrl

Claude Code OpenAI Codex OpenCode Pi Gemini CLI

WHAT YOU CAN BUILD

From simple data extraction to multi-agent workflows. Here's what developers are building with InstructorPHP.

Data Extraction & ETL

Extract structured data from documents, emails, invoices, and reports. Turn unstructured text into typed PHP objects ready for your database.

Instructor Polyglot

Conversational Agents

Build customer support bots, FAQ assistants, and interactive agents that reason, use tools, and maintain conversation state across sessions.

Agents Polyglot

Code Automation

Orchestrate coding agents for automated refactoring, migrations, test generation, and CI/CD workflows. Control multiple agent backends from one script.

AgentCtrl

RAG Pipelines

Build retrieval-augmented generation with Polyglot embeddings and inference. Index documents, search semantically, and generate contextual answers.

Polyglot Instructor

Content Generation

Generate validated, structured content for CMS, e-commerce catalogs, and marketing. Get typed objects with SEO metadata, not raw strings.

Instructor Polyglot

API Integration

Convert natural language to validated API parameters. Classify requests, extract entities, and route them through your existing PHP service layer.

Instructor Agents

PACKAGE COMPARISON

Each package has a clear responsibility. Here's what each one gives you.

Capability	Polyglot	Instructor	Agents	AgentCtrl
LLM Inference		—	—	—
Embeddings		—	—	—
Structured Output	—		—	—
Validation + Retry	—		—	—
Agent Loop	—	—		—
Tool Execution	—	—		—
Lifecycle Hooks	—	—		—
Subagents	—	—		—
Session Persistence	—	—
CLI Agent Control	—	—	—
Sandbox Modes	—	—	—
Streaming			*
* via event listeners

DOCUMENTATION

Instructor

Structured outputs for typed PHP data or plain arrays.


                    cognesy/instructor-struct

Getting Started
Response Models
Validation
Streaming
Output Modes

Package docs

Polyglot

Unified LLM calls and embeddings across 25+ providers.


                    cognesy/instructor-polyglot

Getting Started
Inference
Embeddings
Streaming
Presets

Package docs

Agents

Agent loops, tools, subagents, capabilities, and sessions.


                    cognesy/agents

Getting Started
Agent Loop
Tools
Capabilities
Testing

Package docs

AgentCtrl

Control Claude Code, Codex, OpenCode, Pi, and Gemini from PHP.


                    cognesy/agent-ctrl

Getting Started
Claude Code
Codex
Streaming
Sessions

Package docs

"Start with plain PHP code. Add the AI capability you need. Keep the rest of your application structure the same."

FAQ

Do I need all four packages?

No. Each package is independently installable. Start with the one that solves your immediate problem. The meta-package cognesy/instructor-php installs everything, but you can also install individual packages like cognesy/instructor-polyglot or cognesy/agents separately.

Which LLM provider should I start with?

Any of the 25+ supported providers. OpenAI and Anthropic are the most popular choices. If you want to run models locally, Ollama works out of the box. The API is identical regardless of provider — switching later is a one-line change.

Does it work with Laravel?

Yes — and also with Symfony, CodeIgniter, or plain PHP. InstructorPHP is framework-agnostic by design. There is no service provider, facade, or framework coupling required.

Is it production-ready?

Yes. The library includes automatic validation with retry policies, configurable error handling, event-driven observability, and context caching for cost reduction. It is designed for production use, not just prototyping.

How is this different from using the OpenAI PHP SDK directly?

The OpenAI SDK gives you raw API access to one provider. InstructorPHP gives you structured outputs (typed PHP objects), provider switching (25+ backends through one API), an agent framework, and coding agent orchestration. It handles schema generation, validation, retries, and deserialization for you.

Can I use it for streaming responses?

Yes. Polyglot supports full streaming with deltas, filtering, and mapping. Instructor supports streaming partial object updates. AgentCtrl supports real-time streaming from coding agents with callbacks.

INSTRUCTOR ON OTHER PLATFORMS

Python TypeScript Ruby Elixir

COMMUNITY & SUPPORT

LLMs, structured data, agents — one PHP SDK

Polyglot

Instructor

Agents

AgentCtrl

Install with Composer

Set your API key

Pick the capability you need

Unified LLM API

Structured outputs

Agents

Coding agent control

Framework-agnostic

Type-safe

Composable

Testable

Production-ready

PHP-native

LLM Inference

Embeddings

Coding Agents

Data Extraction & ETL

Conversational Agents

Code Automation

RAG Pipelines

Content Generation

API Integration

Instructor

Polyglot

Agents

AgentCtrl

Do I need all four packages?

Which LLM provider should I start with?

Does it work with Laravel?

Is it production-ready?

How is this different from using the OpenAI PHP SDK directly?

Can I use it for streaming responses?

GitHub

Discord

Twitter / X

Documentation