Download the PHP package pocketarc/ai-workflow without Composer

AI Workflow

Production-ready AI workflows for Laravel. Wraps Prism PHP and routes OpenRouter calls through laravel-integrations for resilient transport: circuit breaking, retries, failure classification, and rate limiting. Adds fallback models, finish reason monitoring, YAML-based prompt management with Mustache templating, request logging with tagging, a middleware pipeline, caching, multimodal support, an eval framework, and Laravel Data integration.

Installation

Publish the config file:

OpenRouter calls are routed through pocketarc/laravel-integrations (installed automatically as a dependency), which owns the circuit breaker, retries, and rate limiting. Publish and run its migrations, then create an OpenRouter integration:

Prism authenticates to OpenRouter with its own OPENROUTER_API_KEY env var, so set that to the same key. The integration row holds the API key as the framework's credential record and carries the circuit-breaker and rate-limit state.

A database is therefore required for OpenRouter requests: the integration row and its transport audit live there. Calls to providers without a registered integration (e.g. anthropic:...) fall back to Prism directly and need no database.

Request logging and the eval framework add their own tables. Publish and run ai-workflow's migrations to enable them:

Prompt Files

Prompts live as Markdown files with YAML front-matter in your configured prompts_path (default: resources/prompts/).

Front-matter fields:

• model (required): Model identifier in provider:model format (e.g. openrouter:google/gemini-3-pro-preview, anthropic:claude-opus-4.5).
• fallback_model (optional): If structured decoding fails, retry with this model. Same provider:model format.
• tags (optional): Array of string tags stored with each request for filtering.
• cache_ttl (optional): Cache responses for this many seconds. Omit to disable caching.
• reasoning (optional): Enable extended thinking / reasoning. Accepts an effort level string (xhigh, high, medium, low, minimal, none) or an integer token budget (e.g. 8000). Automatically translated to provider-specific options (Anthropic budgetTokens, Gemini thinkingLevel/thinkingBudget, OpenRouter reasoning.effort, etc.).
• max_tokens (optional): Override the global max output tokens for this prompt. Defaults to 16384 for text and 32768 for structured responses (configurable in ai-workflow.max_tokens).

The prompt's id is derived from the filename. A file at resources/prompts/my_prompt.md is my_prompt.

Mustache Templating

Prompts support Mustache variables and conditionals:

Load prompts without variables as before:

Usage

Text Responses

Send messages and get a text response with tool-calling support:

Structured Responses

Get structured JSON output matching a schema:

Structured Responses with Laravel Data

If you have spatie/laravel-data installed, you can use Data classes directly. The package generates the schema from the class, validates the response, and retries with feedback on validation failure:

On validation failure, the package appends the error to the conversation and retries up to $maxAttempts (default 3).

Streaming

Stream text responses as a generator of events:

Streaming does not support automatic retries (this is inherent to how streaming APIs work).

Extra Context

Pass a second prompt as shared context that gets prepended to the system prompt:

Tool Registration

Register tools that the AI can call during text conversations:

Set context before making calls to pass runtime data to your tools:

Request Tagging

Tags help you categorize and filter logged requests. Set them in prompt front-matter and/or at runtime:

Tags from both sources are merged and deduplicated. Query with custom builder scopes:

Request Logging

When enabled, every AI call is recorded to the database with enough detail to replay it: system prompt, messages, model, provider, schema, response, token usage, duration, and tags.

Enable logging in your .env:

Execution Grouping

Group related AI calls under a named execution:

Query executions and get aggregate token usage:

Events

Two events are dispatched after every AI call, regardless of whether logging is enabled:

• AiWorkflowRequestCompleted — prompt, method, model, finish reason, usage, duration, execution ID.
• AiWorkflowRequestFailed — prompt, method, model, exception, duration, execution ID.

Sentry Integration

A ready-to-use listener adds Sentry breadcrumbs for AI requests. Register in your EventServiceProvider:

No hard dependency on Sentry — the listener is a no-op if Sentry is not installed.

Caching

Responses can be cached per-prompt using a content-addressable key derived from the request parameters. Set cache_ttl in the prompt front-matter:

Enable caching globally in your .env:

Cache hits skip the API call entirely and do not create log records.

Middleware

Add before/after hooks to all AI requests using a middleware pipeline.

Global Middleware

Register middleware in your config:

Instance Middleware

Add middleware per-instance:

Writing Middleware

Implement AiWorkflowMiddleware:

Guardrails

Abstract base classes for input and output validation:

InputGuardrail validates before the request; OutputGuardrail validates after. Both throw GuardrailViolationException on failure.

Replay Engine

The replay engine lets you re-run recorded AI requests with different models or updated prompts. This is the foundation for evals.

Eval Framework

Evaluate AI outputs by replaying recorded requests from curated datasets across models with pluggable judges.

The workflow: run an AI action, verify the response is correct, add the execution to a named dataset, then eval that dataset against different models to see which ones produce equivalent results.

Building a Dataset

Datasets are collections of known-good executions. Use execution grouping to track AI calls, then add verified executions to a dataset:

Running Evals

This replays every request in the dataset against each model, judges the results, and displays a per-model score table.

Writing a Judge

Implement AiWorkflowEvalJudge:

The package includes AiJudge — an AI-powered judge that semantically compares original and new responses (e.g. {"payer": "John"} vs {"payer": "john"} scores high). For domain-specific evaluation, implement your own judge with custom scoring logic.

Running Evals in Code

Prompt Testing

Run YAML-defined test cases against prompts to verify AI outputs.

Test File Format

Test files live alongside prompts in a tests/ subdirectory:

Running Tests

Resilience

OpenRouter calls run through laravel-integrations, which owns the circuit breaker, retries, and rate limiting. Failures are classified so the breaker reacts correctly:

• 402 / 403 / other 4xx are client errors: not retried, and they never trip the breaker. This stops a billing or access outage from becoming a retry storm.
• 429 is a throttle: retried (honouring Retry-After) without tripping the breaker.
• 5xx, connection errors, and timeouts are upstream faults: retried with backoff and counted toward the breaker.

Backoff is a fixed ~30s pause on rate limits and ~attempt x 2s on server errors, with optional ±25% jitter. Tune it via ai-workflow.retry: times sets the max attempts, and rate_limit_delay_ms, server_error_multiplier_ms, and jitter shape the backoff. When retries are exhausted, the underlying Prism exception propagates.

The breaker state, rate budget, and transport audit live on the integration row.

Fallback Models

If a structured request fails to decode JSON (the model produced invalid output), the package automatically retries with the fallback_model if one is configured in the prompt's front-matter.

Finish Reason Handling

After each AI response, the finish reason is checked:

Testing

The package works with Prism's built-in faking:

Development