Download the PHP package pocketarc/ai-workflow without Composer

AI Workflow

Production-ready AI workflows for Laravel. Wraps Prism PHP with retry logic, fallback models, finish reason monitoring, YAML-based prompt management with Mustache templating, request logging with tagging, middleware pipeline, caching, multimodal support, eval framework, and Laravel Data integration.

Installation

Publish the config file:

No database is required for core functionality. Sending AI requests, prompt management, caching, middleware, streaming, and retry logic all work without migrations. A database is only needed if you enable request logging (AI_WORKFLOW_LOGGING=true) or use the eval framework.

To enable request logging or evals, publish and run the migrations:

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

Retry Behaviour

All requests automatically retry on transient failures with random jitter (±25%) to prevent thundering herd:

• HTTP 429 (rate limit): waits ~30 seconds before retry.
• HTTP 5xx (server error): exponential backoff (~attempt x 2 seconds).
• Connection errors: linear backoff (~attempt x 1 second).
• 3 retries by default, configurable via ai-workflow.retry.times.

Jitter can be disabled by setting ai-workflow.retry.jitter to false.

If all retries are exhausted, a RetriesExhaustedException is thrown with the retry count and original exception.

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