Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions docs/advanced/api-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Load a prompt by name and optional version. Accepts `2`, `'2'`, or `'v2'`. If ve

Caches the loaded prompt if caching is enabled.

**Throws:** `PromptNotFoundException` if the prompt does not exist. `InvalidVersionException` if the specified version does not exist.
**Throws:** `InvalidPromptNameException` if the name is not a valid prompt name. `PromptNotFoundException` if the prompt does not exist. `InvalidVersionException` if the specified version does not exist.

```php
$prompt = $manager->get('order-summary'); // active version
Expand Down Expand Up @@ -70,7 +70,7 @@ Activate a specific version of a prompt. Returns `true` on success.

Accepts the same version formats as `get()`, so `2`, `'2'`, and `'v2'` are equivalent. A version that cannot be parsed throws `InvalidVersionException`.

- **With tracking enabled:** Updates the `prompt_versions` database table.
- **With tracking enabled:** Records the version as active in the `prompt_versions` table, inserting a row if the version has not been activated before, and also writes `metadata.json`.
- **Without tracking:** Writes to `metadata.json` in the prompt directory.

```php
Expand Down Expand Up @@ -316,7 +316,7 @@ Handle the `CommandFinished` event. Only acts on successful `make:agent` command
| `name` | `string` | — | Prompt name. |
| `version` | `int` | `integer` | Version number. |
| `system_prompt` | `string\|null` | — | System prompt content. |
| `user_prompt` | `string` | — | User prompt content. |
| `user_prompt` | `string\|null` | — | User prompt content. |
| `metadata` | `array\|null` | `array` | Version metadata. |
| `is_active` | `bool` | `boolean` | Whether this is the active version. |

Expand Down Expand Up @@ -365,10 +365,21 @@ Thrown when a prompt directory does not exist.

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}]."` |
| 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}]."` |
| `unparseable(string $name, string\|int $version): self` | Creates exception with message: `"Invalid version [{version}] for prompt [{name}]. Use a positive number like [1] or [v1]."` |

### InvalidPromptNameException

`PromptPHP\Deck\Exceptions\InvalidPromptNameException`

Thrown when a prompt name contains characters other than letters, numbers, dots, dashes, and underscores, or begins with a dot.

| Factory Method | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `named(string $name): self` | Creates exception with message: `"Prompt name [{name}] is not valid. Names may contain letters, numbers, dots, dashes, and underscores, and may not begin with a dot."` |

### ConfigurationException

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced/tracking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Stores prompt version records and tracks which version is active.
| `name` | `string` | No | The prompt name (e.g. `order-summary`). |
| `version` | `unsigned int` | No | The version number (e.g. `1`, `2`, `3`). |
| `system_prompt` | `text` | Yes | The system prompt content. |
| `user_prompt` | `text` | No | The user prompt content. |
| `user_prompt` | `text` | Yes | The user prompt content. |
| `metadata` | `json` | Yes | Version metadata as JSON. |
| `is_active` | `boolean` | No | Whether this version is the active version. Default: `false`. |
| `created_at` | `timestamp` | Yes | Creation timestamp. |
Expand Down
2 changes: 1 addition & 1 deletion docs/core/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ Version 2 of prompt [order-summary] activated.

### How it works

- **With database tracking enabled**: Updates the `prompt_versions` table. It sets `is_active = false` on all versions for that prompt, then `is_active = true` on the specified version.
- **With database tracking enabled**: Records the version in the `prompt_versions` table. It sets `is_active = false` on all versions for that prompt, then marks the specified version active, inserting a row if that version has not been activated before. It also writes the `active_version` key to `metadata.json`.
- **Without tracking**: Writes the `active_version` key to the prompt's root `metadata.json` file.

### Error handling
Expand Down
2 changes: 2 additions & 0 deletions docs/core/make-prompt.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,8 @@ All prompt names are automatically converted to **kebab-case** for consistent di

This normalisation applies to both the prompt name and any extra role names provided via `--role`.

After normalisation, the prompt name must contain only letters, numbers, dots, dashes, and underscores, and may not begin with a dot. Directory separators are not converted, so a name such as `Support/Reply` fails with an error instead of creating a nested prompt.

## Configuration

The command respects the following values from `config/deck.php`:
Expand Down
2 changes: 1 addition & 1 deletion docs/core/prompts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -355,7 +355,7 @@ Deck::activate('order-summary', 'v2');

The version accepts the same formats as `Deck::get()`, so `2`, `'2'`, and `'v2'` are equivalent. Anything that cannot be parsed throws `InvalidVersionException`.

**When database tracking is enabled**, this updates the `prompt_versions` table. It sets `is_active = false` on all versions of that prompt, then `is_active = true` on the specified version.
**When database tracking is enabled**, this records the version in the `prompt_versions` table. It sets `is_active = false` on all versions of that prompt, then marks the specified version active, inserting a row if that version has not been activated before. It also writes the `active_version` key to `metadata.json`.

**When tracking is disabled**, it writes the `active_version` key to the prompt's root `metadata.json` file.

Expand Down
Loading