README

Provider health checks for laravel/ai.

What This Package Does

This package adds an Artisan command:

php artisan ai:health

It checks each configured AI provider and reports:

• whether provider config exists
• whether API key is present
• whether a basic request succeeds
• request latency
• optional streaming check

Installation

Install as a normal runtime dependency:

composer require vaibhavjethva/laravel-ai-health

require vs require-dev

• Use require (recommended): if you will run ai:health in CI, staging, or production checks.
• Use require-dev: only if you want local-only usage and do not need this command outside development.

composer require --dev vaibhavjethva/laravel-ai-health

This package uses Laravel package auto-discovery, so no manual service provider registration is required.

Usage

Check all configured providers in config/ai.php:

php artisan ai:health

Check only selected providers:

php artisan ai:health --provider=openai --json
php artisan ai:health --provider=openai --provider=groq

Also test streaming:

php artisan ai:health --stream

Fail CI when any provider is unhealthy/degraded/healthy:

php artisan ai:health --fail-on=unhealthy
php artisan ai:health --fail-on=degraded
php artisan ai:health --fail-on=healthy

Typical Output Meaning

• HEALTHY: request succeeded
• DEGRADED: base request works but streaming check failed
• UNHEALTHY: config/key/request failed

Options

• --provider=* Check one or more specific configured providers by config key name. Example: --provider=openai --provider=groq
• --stream Also perform a streaming request test.
• --json Output machine-readable JSON.
• --fail-on=healthy|degraded|unhealthy Exit with code 1 if any checked provider matches the selected status. Default behavior is equivalent to --fail-on=unhealthy.

Exit Codes

• 0: no failure condition matched.
• 1: at least one provider matched the selected failure condition.

Requirements

• PHP ^8.3
• laravel/ai ^0.2|0.x-dev
• illuminate/support ^11.0|^12.0

Notes

• Providers are read from config('ai.providers').
• Missing API key is treated as unhealthy for providers that require keys.
• ollama can be checked without an API key.

Troubleshooting

• Command not found: run php artisan package:discover and try again.
• All providers show API key is missing: set provider keys in .env and verify config/ai.php mappings.
• Local development with a path repository: run composer update vaibhavjethva/laravel-ai-health -W.