README

Laravel Mailable-like API for LLM prompts with Prism.

Define your prompts as YAML templates + PHP classes. Move text and model settings out of code, separate the system message from the user message, parse responses into typed DTOs, and observe every call via events with USD cost attached — the same way you'd compose a Mailable.

# resources/prompts/greeting.yaml
provider: anthropic
model: claude-sonnet-4-5-20250929

system_prompt: |
  You are a friendly greeting assistant.
  Always respond in JSON with "message" and "tone" fields.

prompt: |
  Say hello to {{ $userName }}.

use Kent013\PrismPrompt\Prompt;

$result = Prompt::load('greeting', ['userName' => 'Alice'])->executeSync();

That's the whole loop. Everything else in this package is a layer on top: DTO mapping, multi-provider fallback, prompt-injection defence, parallel execution with prompt caching, observability, durable operations.

Installation

composer require kent013/laravel-prism-prompt

Publish config:

# Provider defaults, cache, debug
php artisan vendor:publish --tag=prism-prompt-config

# Pricing table (per-model USD rates)
php artisan vendor:publish --tag=prism-prompt-pricing

At a glance

Settings priority

Settings resolve highest-wins:

1. Class property (e.g. protected ?float $temperature = 0.5)
2. YAML field
3. Config default (config('prism-prompt.default_*'))

Subclassing

Use Prompt::load() for the simplest case. When you need typed DTOs, custom message construction, or fluent variables in __construct, subclass:

use Kent013\PrismPrompt\Prompt;

/** @extends Prompt<GreetingResponse> */
class GreetingPrompt extends Prompt
{
    public function __construct(public readonly string $userName)
    {
        parent::__construct();
    }

    protected function parseResponse(string $text): GreetingResponse
    {
        $data = $this->extractJson($text);
        return new GreetingResponse($data['message'], $data['tone']);
    }
}

$result = (new GreetingPrompt('Alice'))->executeSync();

Structured output (recommended for new code, since v0.15.0)

For prompts whose output must conform to a fixed shape, declare a Prism schema via getJsonSchema(). The base will route the call through Prism::structured() and pass the decoded array straight to parseStructured() — no extractJson() regex, no YAML JSON example to drift out of sync.

use Kent013\PrismPrompt\Prompt;
use Prism\Prism\Contracts\Schema;
use Prism\Prism\Schema\{ObjectSchema, StringSchema, NumberSchema};

/** @extends Prompt<GreetingResponse> */
class GreetingPrompt extends Prompt
{
    public function __construct(public readonly string $userName) { parent::__construct(); }

    protected function getJsonSchema(): ?Schema
    {
        return new ObjectSchema(
            name: 'greeting_response',
            description: 'A greeting reply',
            properties: [
                new StringSchema('message', 'the greeting text'),
                new NumberSchema(
                    name: 'tone',
                    description: 'tone score',
                    minimum: 0.0,
                    maximum: 1.0,
                ),
            ],
            requiredFields: ['message', 'tone'],
        );
    }

    /** @param array<string, mixed> $data */
    protected function parseStructured(array $data): GreetingResponse
    {
        return new GreetingResponse($data['message'], (float) $data['tone']);
    }

    // Keep parseResponse as a transitional fallback for Prompt::fake([TextResponseFake])
    // tests, or remove once the legacy path is gone.
    protected function parseResponse(string $text): GreetingResponse
    {
        $data = $this->extractJson($text);
        return new GreetingResponse($data['message'], (float) $data['tone']);
    }
}

getJsonSchema() returning null (the default) keeps the legacy Prism::text() + extractJson() path, so existing subclasses continue to work unchanged. See docs/structured-output.md for the full contract (event payload, fakes, error handling).

YAML lookup (in priority order):

1. $promptName property — relative path from prompts_path
2. Naming convention — GreetingPrompt → greeting.yaml
3. $promptsDirectory — group prompts under a subdirectory

getTemplatePath() is overridable for full control.

Configuration reference

config/prism-prompt.php

config/prism-prompt-pricing.php

Documentation

In-depth topic guides live under docs/:

• yaml-template.md — YAML schema, message structure, override hierarchy
• structured-output.md — getJsonSchema() / parseStructured() for Prism::structured() (v0.15.0+)
• providers.md — multi-provider fallback, runtime API keys
• prompt-injection.md — UserInput, DefensiveInstructions
• parallel-execution.md — PromptPool with prompt caching
• events-and-cost.md — events, withMetadata, USD cost
• testing.md — Prompt::fake() + assertions
• debug-logging.md — listener-based debug
• embedding.md — EmbeddingPrompt
• prompt-operation.md — durable, resumable operations

Runnable examples are under examples/:

License

MIT