Ai Laravel Package

Product Decisions This Supports

• Robustness & Reliability: Strengthen input validation and error handling for AI workflows, reducing runtime failures in production (e.g., blank inputs, insufficient credits, or malformed provider responses). New validations (e.g., rejecting empty reranking lists, blank paths/URLs, or invalid image sizes) align with defensive programming for AI pipelines.
• Cost Optimization & Provider Flexibility:
  • Closure-based provider options for queued embeddings enable dynamic cost control (e.g., fallback to cheaper providers if primary fails).
  • Strict mode opt-in for OpenAI allows granular control over API strictness, reducing unnecessary errors in non-critical workflows.
  • InsufficientCreditsException for OpenRouter/DeepSeek ensures graceful degradation when credits run low, preventing silent failures.
• Developer Experience & Maintainability:
  • PHPStan integration and consistent type hints (e.g., generic types for conversation models) improve code quality and reduce bugs in custom integrations.
  • Documented @throws annotations (e.g., Image::of(), Embeddings::for()) enable better error handling in downstream services.
  • Rehydration of attachments in conversation history simplifies state management for long-running AI workflows (e.g., document analysis agents).
• Expanded Provider Support:
  • Bedrock Converse now supports providerOptions, unlocking AWS Bedrock-specific features (e.g., custom reasoning content).
  • OpenRouter image generation removes text+image restrictions, enabling more flexible multimodal workflows (e.g., generating images with contextual text prompts).
• Observability & Debugging:
  • Consistent provider key resolution and captured usage details (e.g., missing usage patterns for OpenAI-shaped providers) improve monitoring and troubleshooting.
  • Conversation list retrieval from ConversationStore and agent traits enables better auditability of AI interactions.
• Future-Proofing:
  • Pinning GitHub Actions and Dependabot config reduce supply-chain risks, ensuring long-term stability.
  • Unit tests for edge cases (e.g., Anthropic 529 errors, structured agents without strict mode) validate provider resilience for emerging use cases.

When to Consider This Package

• Adopt When:

  • Your Laravel AI workflows require strict input validation (e.g., rejecting blank paths, invalid URLs, or empty embeddings) to prevent runtime errors.
  • You need granular control over provider strictness (e.g., opt-in strict mode for OpenAI to avoid over-fetching errors).
  • Your use case involves cost-sensitive AI (e.g., queued embeddings with closure-based fallback providers or credit monitoring for OpenRouter/DeepSeek).
  • You’re building long-running AI workflows (e.g., document analysis, multimodal pipelines) where attachment rehydration and conversation history are critical.
  • You require better observability (e.g., captured usage details, consistent provider key resolution) for debugging provider-specific issues.
  • Your team prioritizes code quality (PHPStan, type hints) and defensive programming to reduce technical debt in AI integrations.
  • You’re using AWS Bedrock or need OpenRouter’s expanded image generation (e.g., text+image prompts without restrictions).

• Look Elsewhere If:

  • You need framework-agnostic solutions (SDK remains Laravel-specific).
  • Your use case involves real-time, ultra-low-latency systems where validation overhead is prohibitive.
  • You require offline or local model inference (SDK is cloud-provider focused).
  • Your budget allows for custom error handling tailored to niche providers (e.g., unsupported validation rules).
  • You’re using non-Laravel frameworks or need serverless-first deployments (e.g., AWS Lambda, Vercel Edge Functions).

How to Pitch It (Stakeholders)

For Executives: *"The v0.7.0 Laravel AI SDK turns AI integrations into production-grade, cost-controlled, and observable systems. Key upgrades:

• Error-Proof Workflows: Reject invalid inputs (blank paths, empty reranking lists) before they hit providers, saving debug time and API costs.
• Cost Savings: Use closure-based provider options for embeddings to dynamically switch to cheaper providers, and monitor credits (OpenRouter/DeepSeek) to avoid surprise bills.
• Strict Mode Control: Opt into OpenAI strict mode only where needed, reducing unnecessary errors in non-critical workflows.
• Multimodal Flexibility: OpenRouter’s image generation now supports text+image prompts—ideal for creative tools or visual AI agents.
• Future-Proofing: PHPStan integration and consistent type hints reduce bugs, while Bedrock Converse support unlocks AWS-specific AI features.

Example ROI: Launch a document analysis agent that processes PDFs, extracts text, and generates summaries—without runtime failures—while dynamically falling back to cheaper embeddings if costs spike. The SDK handles validation, cost control, and observability, so your team focuses on business logic, not API debugging."

For Engineering Leaders: *"v0.7.0 hardens the SDK for production with critical improvements:

• Input Validation: Blank paths, URLs, or invalid image sizes are rejected early, preventing provider errors. Example:

  // Now throws ValidationException
  AI::image()->of(''); // Blank path rejected
  

• Provider Resilience:
  • InsufficientCreditsException for OpenRouter/DeepSeek ensures graceful degradation.
  • Strict mode opt-in for OpenAI avoids over-fetching errors in non-critical workflows.
• Cost Optimization:
  • Closure provider options for embeddings enable dynamic fallback:

    AI::embeddings()->for('text')->providerOptions(fn () => [
        'provider' => request()->input('fallback_provider') ?? 'openai',
    ]);
    

  • Credit monitoring prevents silent failures when credits run low.
• Multimodal & AWS Bedrock:
  • OpenRouter image generation now supports text+image prompts (e.g., AI::image()->of('A cat wearing a hat')->withTextPrompt('Whimsical')).
  • Bedrock Converse supports providerOptions, unlocking custom reasoning content.
• Observability:
  • Captured usage details (e.g., missing OpenAI usage patterns) improve debugging.
  • Conversation attachment rehydration simplifies state management for long-running workflows.
• Code Quality:
  • PHPStan level 1 and generic types reduce runtime type errors.
  • Documented @throws annotations (e.g., Image::of()) enable better error handling in your codebase.

Use it for:

• Cost-sensitive AI: Dynamic provider fallback and credit monitoring.
• Robust workflows: Input validation and strict mode control.
• Multimodal apps: OpenRouter’s expanded image generation.
• AWS Bedrock: Custom reasoning content via providerOptions.

Trade-offs:

• Validation overhead may impact ultra-low-latency use cases.
• Still Laravel-only (not framework-agnostic)."

For Developers: *"v0.7.0 makes AI integrations safer, cheaper, and more observable. Here’s what’s new:

Input Validation (No More Silent Failures)

The SDK now rejects invalid inputs before they hit providers:

// Throws ValidationException
AI::embeddings()->for(''); // Empty input rejected
AI::image()->of(''); // Blank path rejected
AI::reranking()->documents([]); // Empty list rejected

Provider-Specific Fixes

• OpenAI Strict Mode: Opt in with @Strict attribute:

  use Laravel\AI\Concerns\Strict;
  class MyAgent implements Strict {}
  

• OpenRouter/DeepSeek Credits: Graceful degradation with InsufficientCreditsException.
• Bedrock Converse: Pass providerOptions for custom reasoning:

  AI::converse()->to(Bedrock::class)->providerOptions(['reasoning' => 'detailed']);
  

Cost & Performance

• Dynamic Provider Fallback: Use closures for queued embeddings:

  AI::embeddings()->for('text')->providerOptions(fn () => [
      'provider' => config('app.fallback_provider'),
  ]);
  

• OpenRouter Image Generation: Now supports text+image prompts:

  AI::image()->of('A cat wearing a hat')->withTextPrompt('Whimsical');
  

Observability & Debugging

• Captured Usage Details: Log missing OpenAI usage patterns automatically.
• Conversation Attachments: Rehydrate files when loading history:

  $conversation = AI::conversation()->find(1)->load('attachments');
  

• PHPStan & Types: Level 1 compliance and generic types reduce runtime errors.

Pro Tips

• **Validate early