Ai Orchestrator Laravel Package

Getting Started

• Install with composer require capell-app/ai-orchestrator (this release line is 1.0.x — pin with ^1.0 and let patch releases flow, since the 1.0.43→1.0.49 span is patch-only).
• Publish and review the config first: php artisan vendor:publish --tag="ai-orchestrator-config". The config file is the source of truth for provider credentials, default driver, timeouts, and model mappings.
• Add provider keys to .env (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY) rather than inlining them in config; reference them via env() only in the config file.
• Look first at: the published config/ai-orchestrator.php, the service provider bindings (to see what contracts/facades are registered), and any Contracts directory shipped with the package — that is where the driver interface and testing seams live.
• First use case: a single synchronous completion through the facade (or a quick injected contract call) in a controller or artisan command to confirm credentials and the default driver work. Once that succeeds, move the same call behind a queued job before wiring it into anything user-facing.

Implementation Patterns

• Facade for scripts, injection for app code. Use the facade in tinker/commands for one-off checks, but inject the package's manager/contract into services and jobs so fakes and custom drivers can be swapped in tests.
• Driver-per-provider. Treat each provider as a driver resolved through the package's manager. Select per call when you need to (structured output from one provider, long-context from another), and set a sane default in config for the 90% case.
• Queue anything that touches a network call. Wrap orchestration in a job (ShouldQueue) with explicit $timeout and $tries, and dispatch the downstream work from the handle() method rather than chaining raw synchronous calls.
• Prompt templates as first-class assets. Keep prompts in dedicated classes or resource files, not inline strings, so they can be versioned and unit-tested. Pass variables through a small DTO rather than an associative array sprawl.
• Streaming vs. structured output. Use streaming for chat-style UIs; use non-streaming for anything that must be parsed into JSON or fed into another pipeline stage. Keep the two code paths separate so a streaming regression doesn't silently break parsing.
• Wrap the package in a thin service. A single AiService (or similar) that owns prompt selection, provider choice, and usage logging keeps the package's API out of your domain code and makes future provider swaps a one-file change.
• Integration tip: emit/log on the package's request/response events (if exposed) rather than logging inside your services — it gives you one place to capture latency, token usage, and errors across every call site.

Gotchas and Tips

• Timeouts compound. Set the package/driver timeout below your queue worker's --timeout and below any HTTP client timeout. A sync call in a web request should have a shorter timeout than a queued one; configure them separately.
• Config caching bites in dev. After editing .env or the config file, run php artisan config:clear. Cached config ignores env() changes and is a common "my key isn't being picked up" cause.
• Rate limits are per-provider. Rely on the package's retry/backoff if it has one; otherwise wrap calls in a Laravel rate limiter keyed by provider. Retrying a 429 without backoff makes it worse.
• Token/cost accounting needs explicit logging. Most orchestration packages will happily burn budget silently. Log usage per call (provider, model, tokens, latency) via an event listener or middleware so you can attribute spend.
• Testing: if the package ships a fake (e.g. Orchestrator::fake()), call it in setUp and assert on dispatched prompts/responses rather than asserting on HTTP. Reset fakes between tests — leaked fakes across test classes cause confusing ordering-dependent failures.
• Extension points to reach for, in order: custom driver registration for a new provider, event listeners for observability, and a prompt resolver if you need per-tenant or per-locale prompts. Avoid subclassing internals; prefer the published config and contracts.
• Pin patch versions in CI lockfiles for reproducibility, but don't be afraid of the patch line — 1.0.43→1.0.49 is patch-only, so no breaking changes are expected; still skim the changelog link before bumping if you depend on a specific driver's behavior.
• Provider-specific quirks leak through. Model names, context windows, and JSON-mode support differ; keep those in config/model maps rather than scattered in code so a provider switch is configuration, not a refactor.