​

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.