Symfony Package Cheatsheet

Code-verified reference for packages/symfony.

Package Wiring

Composer package: - cognesy/instructor-symfony

Namespace root: - Cognesy\Instructor\Symfony\

Bundle entrypoint: - Cognesy\Instructor\Symfony\InstructorSymfonyBundle

Bundle extension alias: - instructor

Service definitions loaded by InstructorSymfonyExtension: - packages/symfony/resources/config/core.yaml - packages/symfony/resources/config/polyglot.yaml - packages/symfony/resources/config/events.yaml - packages/symfony/resources/config/delivery.yaml - packages/symfony/resources/config/agent_ctrl.yaml - packages/symfony/resources/config/agents.yaml - packages/symfony/resources/config/sessions.yaml - packages/symfony/resources/config/telemetry.yaml - packages/symfony/resources/config/logging.yaml - packages/symfony/resources/config/testing.yaml - packages/symfony/resources/config/messenger.yaml

Config Root

Public Symfony config root: - instructor

Top-level keys accepted by Configuration: - connections - embeddings - extraction - http - events - agent_ctrl - agents - sessions - telemetry - logging - testing - delivery

Config Translation

SymfonyConfigProvider is the framework-facing config adapter and container binding for: - Cognesy\Config\Contracts\CanProvideConfig

Typed config objects created from Symfony config: - Cognesy\Polyglot\Inference\Config\LLMConfig - Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig - Cognesy\Instructor\Config\StructuredOutputConfig - Cognesy\Http\Config\HttpClientConfig

Useful provider methods: - llm(string $connection = ''): LLMConfig - embeddings(string $connection = ''): EmbeddingsConfig - structuredOutput(): StructuredOutputConfig - httpClient(): HttpClientConfig - get(string $path, mixed $default = null): mixed - has(string $path): bool

Supported lookup shapes: - instructor.connections.default plus named connections under items or connections - flat instructor.connections.<name> connection maps - legacy default fallback for LLM default selection

Container Surface

Public aliases and services available today: - Cognesy\Config\Contracts\CanProvideConfig - Cognesy\Events\Contracts\CanHandleEvents - Cognesy\Http\HttpClient - Cognesy\Http\Contracts\CanSendHttpRequests - Cognesy\Instructor\Symfony\AgentCtrl\SymfonyAgentCtrl - Cognesy\Instructor\Symfony\AgentCtrl\SymfonyAgentCtrlRuntimes - Cognesy\Polyglot\Inference\Contracts\CanCreateInference - Cognesy\Polyglot\Inference\Inference - Cognesy\Polyglot\Embeddings\Contracts\CanCreateEmbeddings - Cognesy\Polyglot\Embeddings\Embeddings - Cognesy\Instructor\Contracts\CanCreateStructuredOutput - Cognesy\Instructor\StructuredOutput

Registered support services: - Cognesy\AgentCtrl\Builder\ClaudeCodeBridgeBuilder - Cognesy\AgentCtrl\Builder\CodexBridgeBuilder - Cognesy\AgentCtrl\Builder\OpenCodeBridgeBuilder - Cognesy\AgentCtrl\Builder\PiBridgeBuilder - Cognesy\AgentCtrl\Builder\GeminiBridgeBuilder - Cognesy\Instructor\Symfony\Support\SymfonyConfigProvider - Cognesy\Instructor\Symfony\Support\SymfonyEventBusFactory - Cognesy\Instructor\Symfony\Support\SymfonyHttpTransportFactory - Cognesy\Events\Dispatchers\SymfonyEventDispatcher - Cognesy\Events\Dispatchers\EventDispatcher - Cognesy\Polyglot\Inference\InferenceRuntime - Cognesy\Polyglot\Embeddings\EmbeddingsRuntime - Cognesy\Instructor\StructuredOutputRuntime - Cognesy\Instructor\Symfony\Delivery\Progress\ProgressEventDispatcher - Cognesy\Instructor\Symfony\Delivery\Progress\Contracts\CanHandleProgressUpdates - Cognesy\Instructor\Symfony\Delivery\Cli\SymfonyCliObservationFormatter - Cognesy\Instructor\Symfony\Delivery\Cli\SymfonyCliObservationPrinter - Cognesy\Telemetry\Application\Telemetry - Cognesy\Telemetry\Domain\Contract\CanExportObservations - Cognesy\Instructor\Symfony\Telemetry\NullTelemetryExporter - Cognesy\Instructor\Symfony\Support\SymfonyLoggingFactory

Event Wiring

The bundle owns CanHandleEvents through a package-local event bus: - Cognesy\Events\Contracts\CanHandleEvents -> Cognesy\Events\Dispatchers\EventDispatcher

Bridge behavior: - the package creates a Cognesy\Events\Dispatchers\SymfonyEventDispatcher bridge around Symfony's event_dispatcher when available - the package event bus uses that bridge as its parent when instructor.events.dispatch_to_symfony is truthy - legacy instructor.events.bridge_to_symfony is still honored as a fallback key - if neither key is set, bridging defaults to true

HTTP Transport

The bundle owns CanSendHttpRequests through Cognesy\Http\HttpClient.

Transport rules implemented by SymfonyHttpTransportFactory: - instructor.http.driver: symfony uses Symfony's http_client service when it is available - instructor.http.driver: framework and instructor.http.driver: http_client are normalized to symfony - if the Symfony client service is missing, or the configured driver is not symfony, the package falls back to the standard HttpClientBuilder driver resolution path

Runtime Services

AgentCtrl: - Cognesy\Instructor\Symfony\AgentCtrl\SymfonyAgentCtrl is the package-owned container entrypoint for CLI code-agent builders - Cognesy\Instructor\Symfony\AgentCtrl\SymfonyAgentCtrlRuntimes is the package-owned registry for context-specific AgentCtrl execution adapters - backend builder services are public and non-shared for ClaudeCodeBridgeBuilder, CodexBridgeBuilder, OpenCodeBridgeBuilder, PiBridgeBuilder, and GeminiBridgeBuilder - named service IDs exist for instructor.agent_ctrl, instructor.agent_ctrl.builder.default, and instructor.agent_ctrl.builder.<backend> - backend builders inherit shared defaults from instructor.agent_ctrl.defaults and per-backend overrides from instructor.agent_ctrl.backends.<backend> - builder access is guarded by instructor.agent_ctrl.enabled - runtime service IDs exist for instructor.agent_ctrl.runtimes, instructor.agent_ctrl.runtime.cli, instructor.agent_ctrl.runtime.http, and instructor.agent_ctrl.runtime.messenger - runtime adapters expose explicit policy for cli, http, and messenger entrypoints so Symfony applications can check whether inline execution is allowed or should be handed off to Messenger - runtime adapters also expose continuation seams through continuationPolicy(), continuation(), continueLast(), resumeSession(), and handoff(AgentResponse) - continue_last references are same-context only; use handoff() / resumeSession() when handing work from HTTP or CLI into Messenger

Inference: - Cognesy\Polyglot\Inference\InferenceRuntime is created from LLMConfig, CanHandleEvents, and CanSendHttpRequests - Cognesy\Polyglot\Inference\Contracts\CanCreateInference aliases that runtime - Cognesy\Polyglot\Inference\Inference is registered as a public service

Embeddings: - Cognesy\Polyglot\Embeddings\EmbeddingsRuntime is created from EmbeddingsConfig, CanHandleEvents, and CanSendHttpRequests - Cognesy\Polyglot\Embeddings\Contracts\CanCreateEmbeddings aliases that runtime - Cognesy\Polyglot\Embeddings\Embeddings is registered as a public service

Structured output: - Cognesy\Instructor\StructuredOutputRuntime is created from LLMConfig, StructuredOutputConfig, CanHandleEvents, and CanSendHttpRequests - Cognesy\Instructor\Contracts\CanCreateStructuredOutput aliases that runtime - Cognesy\Instructor\StructuredOutput is registered as a public service

Service File Status

Service files that are currently placeholder-only: - packages/symfony/resources/config/agents.yaml - packages/symfony/resources/config/sessions.yaml - packages/symfony/resources/config/testing.yaml

Service files that now back real package behavior: - packages/symfony/resources/config/core.yaml - packages/symfony/resources/config/polyglot.yaml - packages/symfony/resources/config/events.yaml - packages/symfony/resources/config/delivery.yaml - packages/symfony/resources/config/agent_ctrl.yaml - packages/symfony/resources/config/telemetry.yaml - packages/symfony/resources/config/logging.yaml - packages/symfony/resources/config/messenger.yaml

That means the current implemented Symfony surface includes: - bundle registration - config tree and config translation - AgentCtrl container entrypoints and runtime adapters - core event wiring - HTTP transport wiring - public inference, embeddings, and structured output services - native-agent registry and session-store seams - telemetry services and lifecycle hooks - logging services and presets - progress projection, CLI observation, and Messenger delivery seams - repository-local testing helpers and documented override patterns

Still intentionally repository-local or not yet published as public runtime API: - classes under packages/symfony/tests/Support - split-package publication bootstrap and Packagist registration

Documentation

Reference docs: - packages/symfony/README.md - packages/symfony/docs/overview.md - packages/symfony/docs/configuration.md - packages/symfony/docs/quickstart.md - packages/symfony/docs/runtime-surfaces.md - packages/symfony/docs/sessions.md - packages/symfony/docs/testing.md - packages/symfony/docs/telemetry.md - packages/symfony/docs/logging.md - packages/symfony/docs/delivery.md - packages/symfony/docs/operations.md - packages/symfony/docs/migration.md