Ai Batch Bundle Laravel Package

Getting Started

This release exposes the package's batch-processing workflow as Artisan commands, which is the fastest way to get productive without writing any PHP. Start by installing the package and running php artisan list ai to confirm the five commands are registered (ai:batch:create, ai:batch:list, ai:batch:status, ai:batch:wait, ai:batch:download). Your first end-to-end run is: create a batch with ai:batch:create, poll it with ai:batch:status (or block on ai:batch:wait), then retrieve output with ai:batch:download. Check config/ for any published config file first — API credentials and default model/endpoint are almost certainly read from there or from .env, and the commands will fail confusingly if they are missing. Look at the command signatures (php artisan help ai:batch:create) to find the input file path, model, and completion-window options before writing any code.

Implementation Patterns

• CLI-first prototyping. Use the commands to validate your request payload (JSONL input, model, endpoint) before wiring batch submission into application code. Once a create → wait → download cycle succeeds from the terminal, port the same arguments into your service/job.
• Scheduled polling. ai:batch:status is designed for cron/scheduler use — register it in routes/console.php or Kernel::schedule() at a short interval, and use it to transition local batch records (e.g. pending → completed) and dispatch follow-up jobs.
• Blocking vs non-blocking. For long-running workloads run ai:batch:create then hand the batch ID to ai:batch:wait inside a queued job (with a generous $timeout), rather than blocking a web request. For interactive use, prefer the status + download pair.
• Idempotent download. Treat ai:batch:download as the terminal step: store the batch ID on your own model, download results into storage, and guard the download step so re-running it does not double-process results.
• Integration tip: the commands are thin wrappers over the underlying batch client — the cleanest production pattern is to call the same service/repository the commands use from your own jobs, keeping the CLI for ops/debugging and the service for application logic.

Gotchas and Tips

• Batch APIs are asynchronous and eventually consistent. A batch can sit in validating for a while before in_progress; ai:batch:status returning non-terminal states is expected, not a bug. Don't build retry logic that resubmits on every non-completed status.
• ai:batch:wait will block your terminal/worker. Always bound it with the job/command timeout and your platform's max execution time; on shared hosting or default PHP-FPM timeouts it will be killed mid-wait.
• Input file format is the usual culprit. Batch APIs typically require newline-delimited JSON (JSONL) with a strict per-line schema; a trailing newline, BOM, or pretty-printed JSON will cause the whole batch to fail validation. Validate the file before create.
• Credentials and org/project scoping. If you use multiple API keys or org/project scopes, confirm which the commands resolve — a missing key usually surfaces as an auth error only at create or download time.
• Failure handling is per-request, not per-batch. A completed batch can still contain individual failed requests; inspect the error file/field rather than assuming success from the batch status alone.
• Cleanup: downloaded result files and stored batch IDs accumulate. Prune processed batches and output files on a schedule to avoid unbounded storage growth.
• Debugging tip: run commands with -v/-vvv and check storage/logs/laravel.log; the package almost certainly logs the raw API response at debug level, which is the quickest way to see validation errors that the console output truncates.