Laravel Ai Orbit Laravel Package

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.

Gotchas and Tips

• 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.