Skip to content

api-reference.md

Latest commit

 

History

History
422 lines (282 loc) · 12.5 KB

api-reference.md

File metadata and controls

422 lines (282 loc) · 12.5 KB

API Reference

PromptManager

Veeqtoh\PromptDeck\PromptManager

The core service class responsible for loading, caching, versioning, and tracking prompts. Registered as a singleton in the service container.

Constructor

public function __construct(
    string $basePath,
    string $extension,
    Cache $cache,
    Config $config
)
Parameter Type Description
$basePath string Base directory where prompt files are stored.
$extension string File extension for prompt templates (e.g. md).
$cache Illuminate\Contracts\Cache\Repository Cache store instance.
$config Illuminate\Contracts\Config\Repository Configuration repository.

Methods

get(string $name, ?int $version = null): PromptTemplate

Load a prompt by name and optional version. If version is null, the active version is resolved automatically. Returns a PromptTemplate instance.

Caches the loaded prompt if caching is enabled.

Throws: PromptNotFoundException if the prompt does not exist. InvalidVersionException if the specified version does not exist.

$prompt = $manager->get('order-summary');       // active version
$prompt = $manager->get('order-summary', 2);    // specific version

active(string $name): PromptTemplate

Load the active version of a prompt. Equivalent to calling get($name) without a version.

$prompt = $manager->active('order-summary');

versions(string $name): array

List all versions for a prompt. Returns an array of version info sorted in ascending order.

Throws: PromptNotFoundException if the prompt directory does not exist.

$versions = $manager->versions('order-summary');
// [
//     ['version' => 1, 'path' => '/path/to/v1', 'metadata' => [...]],
//     ['version' => 2, 'path' => '/path/to/v2', 'metadata' => [...]],
// ]

activate(string $name, int $version): bool

Activate a specific version of a prompt. Returns true on success.

  • With tracking enabled: Updates the prompt_versions database table.
  • Without tracking: Writes to metadata.json in the prompt directory.
$manager->activate('order-summary', 2);

track(string $promptName, int $version, array $data): void

Record a prompt execution for tracking. No-op if tracking is disabled.

$manager->track('order-summary', 2, [
    'input'    => ['message' => 'Hello'],
    'output'   => 'Hi there!',
    'tokens'   => 50,
    'latency'  => 120.5,
    'cost'     => 0.001,
    'model'    => 'gpt-4o',
    'provider' => 'openai',
    'feedback' => ['rating' => 5],
]);

PromptTemplate

Veeqtoh\PromptDeck\PromptTemplate

Represents a loaded prompt with its roles, metadata, and interpolation capabilities. Implements Illuminate\Contracts\Support\Arrayable.

Constructor

public function __construct(
    protected string $name,
    protected int $version,
    protected array $roles = [],
    protected array $metadata = [],
)
Parameter Type Description
$name string The prompt name.
$version int The resolved version number.
$roles array<string, string> Role name → raw content map.
$metadata array Prompt metadata from metadata.json.

Methods

role(string $role, array $variables = []): string

Render a role's content with variable interpolation. Returns an empty string if the role does not exist.

$content = $prompt->role('system', ['tone' => 'friendly']);

raw(string $role): string

Get the raw content for a role without interpolation. Returns an empty string if the role does not exist.

$template = $prompt->raw('system');

has(string $role): bool

Check whether a specific role exists in this prompt.

if ($prompt->has('assistant')) {
    // ...
}

roles(): array

Get all available role names.

$prompt->roles(); // ['system', 'user', 'assistant']

toMessages(array $variables = [], ?array $only = null): array

Build a messages array for AI API consumption. Returns an array of ['role' => '...', 'content' => '...'] entries.

Parameter Type Description
$variables array Variables to interpolate into every role.
$only array|null Limit to these roles (preserves order). null = all roles. 
$messages = $prompt->toMessages(['tone' => 'concise'], ['system', 'user']);

version(): int

Get the resolved version number.

$prompt->version(); // 2

name(): string

Get the prompt name.

$prompt->name(); // 'order-summary'

metadata(): array

Get the prompt metadata. Returns an empty array if no metadata is defined.

$prompt->metadata(); // ['description' => '...', 'variables' => [...]]

toArray(): array

Convert the prompt to an array (implements Arrayable).

$prompt->toArray();
// ['name' => '...', 'version' => 2, 'roles' => [...], 'metadata' => [...]]

__call(string $method, array $parameters): string

Dynamic role access via method call. Any method name is treated as a role name.

$prompt->system(['tone' => 'friendly']);   // renders 'system' role
$prompt->assistant(['context' => '...']);  // renders 'assistant' role
$prompt->custom_role();                    // renders 'custom_role' role

PromptDeck Facade

Veeqtoh\PromptDeck\Facades\PromptDeck

Static proxy to the PromptManager singleton.

Available Methods

Method Returns Description
PromptDeck::get(string $name, ?int $version = null) PromptTemplate Load a prompt by name and optional version.
PromptDeck::active(string $name) PromptTemplate Load the active version of a prompt.
PromptDeck::versions(string $name) array List all versions for a prompt.
PromptDeck::activate(string $name, int $version) bool Activate a specific version.
PromptDeck::track(string $name, int $version, array $data) void Record a prompt execution.

HasPromptTemplate Trait

Veeqtoh\PromptDeck\Concerns\HasPromptTemplate

Trait for integrating Prompt Deck templates with Laravel AI SDK agents.

Methods

promptName(): string

Get the prompt name. Defaults to the kebab-cased class name (e.g. SalesCoach → sales-coach). Override to use a custom name.

promptVersion(): ?int

Get the prompt version to load. Returns null by default (active version). Override to pin to a specific version.

promptVersion(): ?int

Get the prompt version to load. Returns null by default (active version). Override to pin to a specific version.

promptVariables(): array

Get variables for prompt template interpolation. Returns an empty array by default. Override to provide dynamic context.

promptTemplate(): PromptTemplate

Get the loaded PromptTemplate instance. Cached for the lifetime of the object.

instructions(): Stringable|string

Get the system instructions from the prompt template. Loads the system role and interpolates promptVariables(). Satisfies the AI SDK Agent contract.

promptMessages(?array $only = null): array

Get prompt roles as messages. By default returns all roles except system. Returns Message[] when the AI SDK is installed, or raw ['role' => '...', 'content' => '...'] arrays otherwise.

Parameter Type Description
$only array|null Limit to specific roles. null = all non-system roles.

forgetPromptTemplate(): static

Clear the cached PromptTemplate, forcing a fresh load on next access. Returns $this for fluent chaining.

TrackPromptMiddleware

Veeqtoh\PromptDeck\Ai\TrackPromptMiddleware

Laravel AI SDK agent middleware that automatically tracks prompt executions.

Methods

handle(mixed $prompt, Closure $next): mixed

Handle the incoming agent prompt. Measures latency and records execution data using PromptManager::track() after the response completes.

Only tracks agents that use the HasPromptTemplate trait (i.e. agents with a promptName() method).

AfterMakeAgent Listener

Veeqtoh\PromptDeck\Listeners\AfterMakeAgent

Listens for the Laravel AI SDK's make:agent command and automatically scaffolds a corresponding Prompt Deck prompt.

Methods

handle(CommandFinished $event): void

Handle the CommandFinished event. Only acts on successful make:agent commands. Converts the agent name to kebab-case and runs make:prompt if the prompt doesn't already exist.

Models

PromptVersion

Veeqtoh\PromptDeck\Models\PromptVersion

Attribute Type Cast Description
name string — Prompt name.
version int integer Version number.
system_prompt string|null — System prompt content.
user_prompt string — User prompt content.
metadata array|null array Version metadata.
is_active bool boolean Whether this is the active version.

PromptExecution

Veeqtoh\PromptDeck\Models\PromptExecution

Attribute Type Cast Description
prompt_name string — Prompt name.
prompt_version int integer Version number.
input array|null array Input data (JSON).
output string|null — Response text.
tokens int|null integer Total tokens.
latency_ms int|null integer Latency in milliseconds.
cost string|null decimal:6 Cost (6 decimal places).
model string|null — AI model used.
provider string|null — AI provider.
feedback array|null array Feedback data (JSON).

Exceptions

All Prompt Deck exceptions extend the base PromptDeckException class.

PromptDeckException

Veeqtoh\PromptDeck\Exceptions\PROMPTDECKException

Abstract base exception for all Prompt Deck errors. Extends PHP's Exception class.

PromptNotFoundException

Veeqtoh\PromptDeck\Exceptions\PromptNotFoundException

Thrown when a prompt directory does not exist.

Factory Method Description
named(string $name): self Creates exception with message: "Prompt [{name}] not found."

InvalidVersionException

Veeqtoh\PromptDeck\Exceptions\InvalidVersionException

Thrown when a requested version does not exist or no versions are found.

Factory Method Description
forPrompt(string $name, int $version): self Creates exception with message: "Version {version} for prompt [{name}] does not exist."
noVersions(string $name): self Creates exception with message: "No versions found for prompt [{name}]."

ConfigurationException

Veeqtoh\PromptDeck\Exceptions\ConfigurationException

Thrown when Prompt Deck configuration is invalid.

Factory Method Description
invalidPath(string $path): self Creates exception with message: "Prompts path [{path}] is not a directory or is not writable."

PromptRenderingException

Veeqtoh\PromptDeck\Exceptions\PromptRenderingException

Thrown when prompt rendering fails.

Factory Method Description
dueToMissingVariable(string $variable, string $promptName): self Creates exception with message: "Cannot render prompt [{promptName}]: missing required variable '{variable}'."