Getting Started

Treat v2.0.0 as a major upgrade: start with the compare link (v1.3.2...v2.0.0) and the package’s upgrade guide before touching application code. A major bump from 1.x almost always means breaking API, config, or behavior changes.
Run composer require ashrafic/laravel-ai-orbit:^2.0 in a branch, then immediately republish config and any assets:
- php artisan vendor:publish --tag=ai-orbit-config
- check for new migration/publish tags in the v2 docs.
First use case: wire one provider in config/ai-orbit.php, then call the package’s facade/manager from a Tinker session or a single artisan command to confirm credentials, HTTP client behavior, and default model selection before integrating into controllers/jobs.
Look first at:
1. the v2 changelog diff for renamed classes, removed methods, and config key changes;
2. the package service provider for bindings and auto-discovery assumptions;
3. the default config file for provider/driver defaults and timeout settings.

Implementation Patterns

Provider abstraction: keep provider/model selection in config and resolve the package manager/facade from the container. Avoid hard-coding model names in controllers; use config or a small application-level factory so v2 provider changes are isolated.
Agent/tool workflows: define reusable agent or prompt classes rather than inline calls. Keep instructions, tool definitions, and output schemas in dedicated classes so they can be tested independently of HTTP calls.
Queued AI calls: move non-interactive generation, summarization, and tool-calling flows into jobs. Set job $timeout and $tries higher than the package’s HTTP timeout, and use queue:work --timeout consistently.
Streaming: for user-facing chat, stream from a controller/route and keep the provider call thin. For anything that mutates state, prefer queued non-streaming jobs so retries and failures are observable.
Testing: use Laravel’s HTTP fake or the package’s fake/test double (check v2 docs) to assert prompts, model selection, and tool payloads without spending tokens. Add one “smoke” integration test against a real provider in a separate suite.
Integration tip: wrap the package behind a small application service (e.g. AiOrbitService) so future major upgrades only require changes in one place.

v2 breaking changes are the main risk: diff v1.3.2 to v2.0.0 for renamed namespaces, changed method signatures, removed config keys, and altered default behavior. Do not assume a drop-in upgrade from 1.x.
Config caching: after publishing/editing config/ai-orbit.php, run php artisan config:clear in local/dev. In production, ensure deploy scripts run config:cache after the new config is in place.
Timeouts and retries: provider HTTP timeouts, queue worker timeouts, and retry counts can silently conflict. Log the package’s request/response metadata where available and align all three.
Rate limits and cost: add application-level throttling and token/usage logging around day-to-day calls. Major versions sometimes change default models or retry behavior, which can change spend.
Extension points: check the v2 service provider and manager bindings before subclassing. Prefer binding your own implementation through the container over monkey-patching package internals.
Debugging: enable package debug logging if available, and inspect the underlying HTTP client exceptions. In tests, assert the outgoing request body rather than only the final response.