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

# Laravel

# Laravel Package Cheatsheet

Code-verified reference for `packages/laravel`.

## Package Wiring

Auto-discovered provider:

* `Cognesy\Instructor\Laravel\InstructorServiceProvider`

Auto-discovered aliases:

* `StructuredOutput` -> `Cognesy\Instructor\Laravel\Facades\StructuredOutput`
* `Inference` -> `Cognesy\Instructor\Laravel\Facades\Inference`
* `Embeddings` -> `Cognesy\Instructor\Laravel\Facades\Embeddings`
* `AgentCtrl` -> `Cognesy\Instructor\Laravel\Facades\AgentCtrl`

## Service Container Bindings

Provided by `InstructorServiceProvider::provides()`:

* `Cognesy\Events\Contracts\CanHandleEvents`
* `Cognesy\Config\Contracts\CanProvideConfig`
* `Cognesy\Http\HttpClient`
* `Cognesy\Http\Contracts\CanSendHttpRequests`
* `Cognesy\Agents\Template\AgentDefinitionRegistry`
* `Cognesy\Polyglot\Inference\Inference`
* `Cognesy\Polyglot\Embeddings\Embeddings`
* `Cognesy\Instructor\StructuredOutput`
* `Cognesy\Polyglot\Inference\Contracts\CanCreateInference`
* `Cognesy\Polyglot\Embeddings\Contracts\CanCreateEmbeddings`
* `Cognesy\Instructor\Contracts\CanCreateStructuredOutput`
* `Cognesy\Agents\Template\Contracts\CanManageAgentDefinitions`
* `Cognesy\Agents\Tool\ToolRegistry`
* `Cognesy\Agents\Tool\Contracts\CanManageTools`
* `Cognesy\Agents\Capability\AgentCapabilityRegistry`
* `Cognesy\Agents\Capability\CanManageAgentCapabilities`
* `Cognesy\Agents\Capability\StructuredOutput\SchemaRegistry`
* `Cognesy\Agents\Capability\StructuredOutput\CanManageSchemas`
* `Cognesy\Agents\Session\Store\InMemorySessionStore`
* `Cognesy\Instructor\Laravel\Agents\Session\DatabaseSessionStore`
* `Cognesy\Agents\Session\Contracts\CanStoreSessions`
* `Cognesy\Agents\Session\SessionRepository`
* `Cognesy\Agents\Session\Contracts\CanManageAgentSessions`
* `Cognesy\Agents\Template\Factory\DefinitionLoopFactory`
* `Cognesy\Agents\Template\Contracts\CanInstantiateAgentLoop`
* `Cognesy\Agents\Session\SessionRuntime`
* `Cognesy\Agents\Broadcasting\BroadcastConfig`
* `Cognesy\Instructor\Laravel\Agents\Broadcasting\NullAgentEventTransport`
* `Cognesy\Instructor\Laravel\Agents\Broadcasting\LaravelAgentEventTransport`
* `Cognesy\Agents\Broadcasting\CanBroadcastAgentEvents`
* `Cognesy\Instructor\Laravel\Agents\Broadcasting\LaravelAgentBroadcasting`
* `Cognesy\Telemetry\Application\Registry\TraceRegistry`
* `Cognesy\Telemetry\Application\Telemetry`
* `Cognesy\Telemetry\Domain\Contract\CanExportObservations`
* `Cognesy\Telemetry\Domain\Contract\CanFlushTelemetry`
* `Cognesy\Telemetry\Domain\Contract\CanShutdownTelemetry`
* `Cognesy\Telemetry\Application\Projector\CanProjectTelemetry`
* `Cognesy\Telemetry\Application\Projector\RuntimeEventBridge`
* `Cognesy\Instructor\Laravel\Testing\StructuredOutputFake`
* `Cognesy\Instructor\Laravel\Testing\AgentCtrlFake`
* `Cognesy\Instructor\Laravel\Testing\NativeAgentTesting`

## Facades

`StructuredOutput` facade:

* `StructuredOutput::connection(string $name): Cognesy\Instructor\StructuredOutput|StructuredOutputFake`
* `StructuredOutput::fromConfig(LLMConfig $config): Cognesy\Instructor\StructuredOutput|StructuredOutputFake`
* `StructuredOutput::fake(array $responses = []): StructuredOutputFake`
* forwards to `Cognesy\Instructor\StructuredOutput` (for example: `with(...)->get()`)

`Inference` facade:

* `Inference::connection(string $name): Cognesy\Polyglot\Inference\Inference|InferenceFake`
* `Inference::fromConfig(LLMConfig $config): Cognesy\Polyglot\Inference\Inference|InferenceFake`
* `Inference::fake(array $responses = []): InferenceFake`
* forwards to `Cognesy\Polyglot\Inference\Inference` (for example: `with(...)->get()`)

`Embeddings` facade:

* `Embeddings::connection(string $name): Cognesy\Polyglot\Embeddings\Embeddings|EmbeddingsFake`
* `Embeddings::fromConfig(EmbeddingsConfig $config): Cognesy\Polyglot\Embeddings\Embeddings|EmbeddingsFake`
* `Embeddings::fake(array $responses = []): EmbeddingsFake`
* forwards to `Cognesy\Polyglot\Embeddings\Embeddings` (for example: `withInputs(...)->first()`)

`AgentCtrl` facade:

* `AgentCtrl::fake(array $responses = []): AgentCtrlFake`
* `AgentCtrl::claudeCode(): ClaudeCodeBridgeBuilder|AgentCtrlFake`
* `AgentCtrl::codex(): CodexBridgeBuilder|AgentCtrlFake`
* `AgentCtrl::openCode(): OpenCodeBridgeBuilder|AgentCtrlFake`
* `AgentCtrl::make(AgentType $type): ClaudeCodeBridgeBuilder|CodexBridgeBuilder|OpenCodeBridgeBuilder|AgentCtrlFake`

## Testing Fakes

`StructuredOutputFake`:

* setup: `respondWith(string $class, mixed $response)`, `respondWithSequence(string $class, array $responses)`
* assertions: `assertExtracted`, `assertExtractedTimes`, `assertNothingExtracted`, `assertExtractedWith`, `assertUsedConnection`, `assertUsedModel`
* inspection: `recorded(): array`

`InferenceFake`:

* setup: `respondWith(string $pattern, string|array $response)`, `respondWithSequence(array $responses)`
* assertions: `assertCalled`, `assertCalledTimes`, `assertNotCalled`, `assertCalledWith`, `assertUsedConnection`, `assertUsedModel`, `assertCalledWithTools`
* inspection: `recorded(): array`

`EmbeddingsFake`:

* setup: `respondWith(string $pattern, array $embedding)`, `withDimensions(int $dimensions)`
* assertions: `assertCalled`, `assertCalledTimes`, `assertNotCalled`, `assertCalledWith`, `assertUsedConnection`, `assertUsedModel`
* results: `get(): object`, `first(): array`, `all(): array`
* inspection: `recorded(): array`

`AgentCtrlFake`:

* builders: `claudeCode()`, `codex()`, `openCode()`, `make(AgentType $type)`
* builder config: `withModel(string $model)`, `withTimeout(int $seconds)`, `inDirectory(string $path)`, `withSandboxDriver(mixed $driver)`, `withMaxRetries(int $retries)`
* builder callbacks: `onText(callable $handler)`, `onToolUse(callable $handler)`, `onComplete(callable $handler)`
* execution: `execute(string $prompt): AgentResponse`, `executeStreaming(string $prompt): AgentResponse`
* assertions: `assertExecuted`, `assertNotExecuted`, `assertExecutedTimes`, `assertExecutedWith`, `assertAgentType`, `assertUsedClaudeCode`, `assertUsedCodex`, `assertUsedOpenCode`, `assertStreaming`
* inspection: `getExecutions(): array`, `reset(): void`
* static helpers: `AgentCtrlFake::response(...)`, `AgentCtrlFake::toolCall(...)`

`NativeAgentTesting`:

* `fakeDriver(?FakeAgentDriver $driver = null, string $capabilityName = 'use_test_driver'): FakeAgentDriver`
* `fakeSessions(?InMemorySessionStore $store = null): InMemorySessionStore`
* `fakeBroadcasts(?RecordingAgentEventTransport $transport = null): RecordingAgentEventTransport`
* `captureTelemetry(?RecordingTelemetryExporter $exporter = null): RecordingTelemetryExporter`

## Artisan Commands

* `instructor:install {--force}`
* `instructor:test {--connection=} {--inference}`
* `make:response-model {name} {--collection} {--nested} {--description=} {--force}`

## Publish Tags

From `InstructorServiceProvider`:

* `instructor-config` -> publishes `config/instructor.php`
* `instructor-stubs` -> publishes `resources/stubs` to `stubs/instructor`
* `instructor-migrations` -> publishes native-agent session migration(s)

## Logging

Logging is configured through `config/instructor.php` and applied from `InstructorServiceProvider`.
The pipeline writes to a Laravel log channel and enriches records with request context.

Relevant env vars:

* `INSTRUCTOR_LOGGING_ENABLED` (default: `true`)
* `INSTRUCTOR_LOGGING_PRESET` (`default` | `production` | `custom`)
* `INSTRUCTOR_LOG_CHANNEL` — Laravel log channel name (default: `stack`)
* `INSTRUCTOR_LOG_LEVEL` — minimum PSR log level (default: `warning`)

Presets:

* `default` — request-enriched development logging with agent-aware templates
* `production` — warning-level logging with streaming/partial noise excluded
* `custom` — uses `logging.channel`, `logging.level`, `logging.exclude_events`, `logging.include_events`, and `logging.templates`

## Config File

Main config file:

* `packages/laravel/resources/config/instructor.php`

Top-level keys:

* `default`
* `connections`
* `embeddings`
* `extraction`
* `http`
* `logging`
* `events`
* `cache`
* `agents`
* `agent_ctrl`
* `telemetry`

Config namespace split:

* `agents` reserves the native `Cognesy\Agents` runtime surface for Laravel container, persistence, and observability integration.
* `agent_ctrl` configures CLI code agents used by the `AgentCtrl` facade.
* `telemetry` configures Laravel-side telemetry export and runtime projector wiring.