Skip to content

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.