Facades

The package provides four main facades for interacting with LLMs and code agents.

StructuredOutput

The primary facade for extracting structured data from text.

Basic Usage

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

$person = StructuredOutput::with(
    messages: 'John Smith is 30 years old',
    responseModel: PersonData::class,
)->get();
// @doctest id="e9d3"

With System Prompt

$person = StructuredOutput::with(
    messages: 'Process this text: John, age 30',
    responseModel: PersonData::class,
    system: 'You are a data extraction assistant.',
)->get();
// @doctest id="8bc8"

With Examples (Few-Shot Learning)

$person = StructuredOutput::with(
    messages: 'Extract: Jane Doe, 25 years',
    responseModel: PersonData::class,
    examples: [
        ['input' => 'Bob is 40', 'output' => new PersonData(name: 'Bob', age: 40)],
    ],
)->get();
// @doctest id="409b"

Switching Connections

$person = StructuredOutput::using('anthropic')->with(
    messages: 'Extract person data...',
    responseModel: PersonData::class,
)->get();
// @doctest id="f425"

Fluent API

$person = StructuredOutput::withMessages('John is 30')
    ->withResponseModel(PersonData::class)
    ->withModel('gpt-4o')
    ->withMaxRetries(3)
    ->get();
// @doctest id="c659"

Return Types

// Get as typed object (default)
$person = StructuredOutput::with(...)->get();

// Get as string
$name = StructuredOutput::with(...)->getString();

// Get as integer
$count = StructuredOutput::with(...)->getInt();

// Get as float
$price = StructuredOutput::with(...)->getFloat();

// Get as boolean
$valid = StructuredOutput::with(...)->getBoolean();

// Get as array
$items = StructuredOutput::with(...)->getArray();
// @doctest id="25a0"

Available Methods

Method	Description
`using(string $preset)`	Switch to a different connection
`with(...)`	Configure extraction with all parameters
`withMessages(...)`	Set input messages
`withResponseModel(...)`	Set the response model class
`withSystem(string)`	Set system prompt
`withPrompt(string)`	Set user prompt template
`withExamples(array)`	Set few-shot examples
`withModel(string)`	Override the model
`withMaxRetries(int)`	Set max retry attempts
`withOptions(array)`	Set additional options
`withOutputMode(OutputMode)`	Set output mode
`withStreaming(bool)`	Enable streaming
`withValidators(...)`	Add custom validators
`withTransformers(...)`	Add data transformers
`get()`	Execute and return result
`stream()`	Execute and return stream

Inference

For raw LLM inference without structured output.

Basic Usage

use Cognesy\Instructor\Laravel\Facades\Inference;

$response = Inference::with(
    messages: 'What is the capital of France?',
)->get();

echo $response; // "The capital of France is Paris."
// @doctest id="d9ec"

With System Message

$response = Inference::with(
    messages: [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user', 'content' => 'Hello!'],
    ],
)->get();
// @doctest id="6060"

JSON Response

$data = Inference::with(
    messages: 'List 3 colors as JSON',
    responseFormat: ['type' => 'json_object'],
)->asJsonData();

// ['colors' => ['red', 'green', 'blue']]
// @doctest id="7a03"

Switching Connections

$response = Inference::using('groq')->with(
    messages: 'Explain quantum computing',
)->get();
// @doctest id="7242"

Available Methods

Method	Description
`using(string $preset)`	Switch connection
`with(...)`	Configure with all parameters
`withMessages(...)`	Set messages
`withModel(string)`	Override model
`withTools(array)`	Add tool definitions
`withToolChoice(...)`	Set tool choice
`withResponseFormat(array)`	Set response format
`withOptions(array)`	Set options
`withStreaming(bool)`	Enable streaming
`get()`	Execute and return text
`asJson()`	Return as JSON string
`asJsonData()`	Return as array
`response()`	Return full response object
`stream()`	Return stream iterator

Embeddings

For generating text embeddings (vector representations).

Basic Usage

use Cognesy\Instructor\Laravel\Facades\Embeddings;

// Get single embedding
$embedding = Embeddings::withInputs('Hello world')->first();
// [0.123, -0.456, 0.789, ...]

// Get multiple embeddings
$embeddings = Embeddings::withInputs([
    'First text',
    'Second text',
])->all();
// @doctest id="8626"

Switching Connections

$embedding = Embeddings::using('ollama')
    ->withInputs('Local embedding test')
    ->first();
// @doctest id="623b"

With Custom Model

$embedding = Embeddings::withInputs('Test')
    ->withModel('text-embedding-3-large')
    ->first();
// @doctest id="def2"

Full Response

$response = Embeddings::withInputs('Test')->get();

$vectors = $response->embeddings;
$usage = $response->usage;
// @doctest id="7cdc"

Available Methods

Method	Description
`using(string $preset)`	Switch connection
`withInputs(string\|array)`	Set input text(s)
`withModel(string)`	Override model
`withOptions(array)`	Set options
`first()`	Get first embedding vector
`all()`	Get all embedding vectors
`get()`	Get full response object

AgentCtrl

For invoking CLI-based code agents (Claude Code, Codex, OpenCode) that can execute code, modify files, and perform complex tasks.

Basic Usage

use Cognesy\Instructor\Laravel\Facades\AgentCtrl;

// Execute a task with Claude Code
$response = AgentCtrl::claudeCode()
    ->execute('Generate a Laravel migration for a users table');

if ($response->isSuccess()) {
    echo $response->text();
}
// @doctest id="176d"

Agent Selection

// Claude Code (Anthropic)
$response = AgentCtrl::claudeCode()
    ->withModel('claude-opus-4-5')
    ->execute('Refactor the User model');

// Codex (OpenAI)
$response = AgentCtrl::codex()
    ->execute('Write unit tests for UserService');

// OpenCode (Multi-model)
$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->execute('Analyze codebase architecture');

// Dynamic selection
use Cognesy\Auxiliary\Agents\Enum\AgentType;

$response = AgentCtrl::make(AgentType::ClaudeCode)
    ->execute('Generate API documentation');
// @doctest id="3a05"

Configuration

$response = AgentCtrl::claudeCode()
    ->withModel('claude-opus-4-5')           // AI model
    ->withTimeout(300)                        // Timeout in seconds
    ->inDirectory(base_path())                // Working directory
    ->withSandboxDriver(SandboxDriver::Host)  // Sandbox isolation
    ->withMaxRetries(3)                       // Retry on failure
    ->execute('Your prompt');
// @doctest id="f8ba"

Streaming

$response = AgentCtrl::claudeCode()
    ->onText(function (string $text) {
        echo $text;
    })
    ->onToolUse(function (string $tool, array $input, ?string $output) {
        echo "Tool: $tool\n";
    })
    ->onComplete(function (AgentResponse $response) {
        echo "Done! Exit code: " . $response->exitCode;
    })
    ->executeStreaming('Generate a REST API');
// @doctest id="05e5"

Response Object

$response = AgentCtrl::claudeCode()->execute('...');

// Main content
$response->text();           // Generated text output
$response->isSuccess();      // True if exitCode is 0

// Metadata
$response->exitCode;         // Process exit code
$response->sessionId;        // Session ID for resuming
$response->agentType;        // Which agent was used

// Usage & cost
$response->usage->input;     // Input tokens
$response->usage->output;    // Output tokens
$response->cost;             // Cost in USD

// Tool calls
foreach ($response->toolCalls as $call) {
    $call->tool;             // Tool name
    $call->input;            // Tool input
    $call->output;           // Tool output
    $call->isError;          // If tool failed
}
// @doctest id="6a17"

Session Management

// First execution
$response = AgentCtrl::claudeCode()
    ->execute('Start refactoring the User model');

$sessionId = $response->sessionId;

// Resume later
$response = AgentCtrl::claudeCode()
    ->resumeSession($sessionId)
    ->execute('Continue with the Address model');
// @doctest id="33fa"

Available Methods

Method	Description
`claudeCode()`	Get Claude Code agent builder
`codex()`	Get Codex agent builder
`openCode()`	Get OpenCode agent builder
`make(AgentType)`	Get agent builder by type
`fake(array $responses)`	Create testing fake
`withModel(string)`	Set AI model
`withTimeout(int)`	Set execution timeout
`inDirectory(string)`	Set working directory
`withSandboxDriver(SandboxDriver)`	Set sandbox isolation
`withMaxRetries(int)`	Set retry count
`onText(callable)`	Stream text callback
`onToolUse(callable)`	Tool use callback
`onComplete(callable)`	Completion callback
`resumeSession(string)`	Resume previous session
`execute(string)`	Execute and return response
`executeStreaming(string)`	Execute with streaming

Dependency Injection

Instead of facades, you can inject services directly:

use Cognesy\Instructor\StructuredOutput;
use Cognesy\Polyglot\Inference\Inference;
use Cognesy\Polyglot\Embeddings\Embeddings;

class MyService
{
    public function __construct(
        private StructuredOutput $structuredOutput,
        private Inference $inference,
        private Embeddings $embeddings,
    ) {}

    public function process(string $text): PersonData
    {
        return $this->structuredOutput
            ->with(messages: $text, responseModel: PersonData::class)
            ->get();
    }
}
// @doctest id="cf24"

This is useful for:

Better testability (easier mocking)
Explicit dependencies
IDE autocompletion

Facade Real-Time Methods

All facades proxy to the underlying service classes. The facades resolve fresh instances from the container, so you can chain methods:

// Each call gets a fresh instance
StructuredOutput::using('openai')->with(...)->get();
StructuredOutput::using('anthropic')->with(...)->get();
// @doctest id="1a6d"

Laravel

Laravel \ Facades

Laravel \ Advanced

Facades

Facades

StructuredOutput

Basic Usage

With System Prompt

With Examples (Few-Shot Learning)

Switching Connections

Fluent API

Return Types

Available Methods

Inference

Basic Usage

With System Message

JSON Response

Switching Connections

Available Methods

Embeddings

Basic Usage

Switching Connections

With Custom Model

Full Response

Available Methods

AgentCtrl

Basic Usage

Agent Selection

Configuration

Streaming

Response Object

Session Management

Available Methods

Dependency Injection

Facade Real-Time Methods

Laravel

Laravel \ Facades

Laravel \ Advanced

​Facades

​StructuredOutput

​Basic Usage

​With System Prompt

​With Examples (Few-Shot Learning)

​Switching Connections

​Fluent API

​Return Types

​Available Methods

​Inference

​Basic Usage

​With System Message

​JSON Response

​Switching Connections

​Available Methods

​Embeddings

​Basic Usage

​Switching Connections

​With Custom Model

​Full Response

​Available Methods

​AgentCtrl

​Basic Usage

​Agent Selection

​Configuration

​Streaming

​Response Object

​Session Management

​Available Methods

​Dependency Injection

​Facade Real-Time Methods

Facades

StructuredOutput

Basic Usage

With System Prompt

With Examples (Few-Shot Learning)

Switching Connections

Fluent API

Return Types

Available Methods

Inference

Basic Usage

With System Message

JSON Response

Switching Connections

Available Methods

Embeddings

Basic Usage

Switching Connections

With Custom Model

Full Response

Available Methods

AgentCtrl

Basic Usage

Agent Selection

Configuration

Streaming

Response Object

Session Management

Available Methods

Dependency Injection

Facade Real-Time Methods