Storage API Reference

This page documents the storage backend functionality of PromptSite.

promptsite.storage.base.StorageBackend

Bases: ABC

Abstract base class defining the storage backend interface.

This class defines the required interface that all storage implementations must provide. It handles the persistence of prompts, versions, and runs.

Implementations should handle the details of storing and retrieving data in their specific storage medium (e.g., file system, git, database).

add_run(prompt_id, version_id, run_data) abstractmethod

Add a new run to a version. Args: prompt_id: str - Prompt identifier version_id: str - Version identifier run_data: Dict - Raw run data

add_version(prompt_id, version_data) abstractmethod

Add a new version data to a prompt. Args: prompt_id: str - Prompt identifier version_data: Dict - Raw version data

create_prompt(prompt_id, prompt_data) abstractmethod

Create a new prompt in storage. Args: prompt_id: str - Unique identifier for the prompt prompt_data: Dict - Raw prompt data containing description, tags, etc.

delete_prompt(prompt_id) abstractmethod

Delete a prompt and all its versions.

get_prompt(prompt_id) abstractmethod

Retrieve raw prompt data by ID. Returns: Optional[Dict]: Raw prompt data if found, None otherwise

get_version(prompt_id, version_id) abstractmethod

Get raw version data. Returns: Optional[Dict]: Version data if found, None otherwise

list_prompts() abstractmethod

Get a list of all prompt IDs. Returns: List[str]: List of prompt IDs

list_versions(prompt_id) abstractmethod

Get all version data for a prompt. Returns: List[Dict]: List of version data dictionaries

update_prompt(prompt_id, prompt_data) abstractmethod

Update prompt data. Args: prompt_id: str - Prompt identifier prompt_data: Dict - Updated prompt data

promptsite.storage.file.FileStorage dataclass

Bases: StorageBackend

File-based storage implementation.

Implements the StorageBackend interface using a file system structure: - prompts//prompt.yaml: Stores prompt metadata - prompts//versions//version.yaml: Stores version data - prompts//versions//runs/.yaml: Stores run data

Attributes:

Name	Type	Description
base_path	str	Base directory for storing all prompt data
prompts_dir	str	Directory containing all prompt data

Example

storage = FileStorage(base_path="/path/to/storage") storage.create_prompt("my-prompt", prompt_data)

_ensure_path_exists(path)

Ensure the directory path exists.

Parameters:

Name	Type	Description	Default
path	str	Directory path to create	required

_get_prompt_path(prompt_id)

Get the full path for a prompt directory.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required

Returns:

Name	Type	Description
str	str	Full path to the prompt directory

_get_run_path(prompt_id, version_id, run_id)

Get the full path for a run file.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_id	str	ID of the version	required
run_id	str	ID of the run	required

Returns:

Name	Type	Description
str	str	Full path to the run YAML file

_get_version_path(prompt_id, version_id)

Get the full path for a version directory.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_id	str	ID of the version	required

Returns:

Name	Type	Description
str	str	Full path to the version directory

_path_exists(path)

Check if a path exists.

Parameters:

Name	Type	Description	Default
path	str	Path to check	required

Returns:

Name	Type	Description
bool	bool	True if path exists, False otherwise

_read_yaml(path)

Read data from a YAML file.

Parameters:

Name	Type	Description	Default
path	str	Path to the YAML file	required

Returns:

Type	Description
Optional[Dict]	Optional[Dict]: The loaded YAML data or None if file not found

_remove_directory(path)

Remove a directory and its contents if it exists.

Parameters:

Name	Type	Description	Default
path	str	Path to the directory to remove	required

_remove_file(path)

Remove a file if it exists.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to remove	required

_write_yaml(path, data)

Write data to a YAML file.

Parameters:

Name	Type	Description	Default
path	str	Path to the YAML file	required
data	Dict	Data to write to the file	required

add_run(prompt_id, version_id, run_data)

Add a new run to a specific version of a prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_id	str	ID of the version	required
run_data	Dict	Run data to store Required keys: - run_id: str	required

Note

Creates the runs directory if it doesn't exist

add_version(prompt_id, version_data)

Add a new version to an existing prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_data	Dict	Version data to add Required keys: - content: str - created_at: datetime - version_id: str Optional keys: - runs: List[Dict] - variables: Dict	required

Raises:

Type	Description
ValueError	If the prompt doesn't exist

create_prompt(prompt_id, prompt_data)

Create a new prompt in storage.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
prompt_data	Dict	Dictionary containing prompt metadata and initial version Expected format: { "versions": [{"version_id": str, "content": str, ...}], ...other metadata... }	required

Raises:

Type	Description
KeyError	If prompt_data doesn't contain required version data

delete_prompt(prompt_id)

Delete a prompt and all its associated data.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt to delete	required

Note

Silently succeeds if the prompt doesn't exist

get_prompt(prompt_id, exclude_versions=False)

Get prompt data including versions.

get_version(prompt_id, version_id)

Get a specific version of a prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_id	str	ID of the version	required

Returns:

Type	Description
Optional[Dict]	Dictionary containing version data.

list_prompts(exclude_versions=False)

List all prompts in storage with their complete information.

Returns:

Type	Description
List[Dict]	List of prompt dictionaries containing all metadata, versions, and runs

list_runs(prompt_id, version_id)

List all runs for a specific version.

Returns:

Type	Description
List[Dict]	List of dictionaries containing run data.
List[Dict]	Each dictionary contains the following keys:
List[Dict]	run_id: str
List[Dict]	created_at: datetime

list_versions(prompt_id, exclude_runs=False)

List all versions for a specific prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
exclude_runs	bool	Whether to exclude runs from the version data	False

Returns:

Type	Description
List[Dict]	List of dictionaries containing version data.
List[Dict]	Each dictionary contains the following keys:
List[Dict]	version_id: str
List[Dict]	content: str
List[Dict]	created_at: datetime

• runs: List[Dict]

update_prompt(prompt_id, prompt_data)

Update an existing prompt's metadata and versions.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt to update	required
prompt_data	Dict	Updated prompt data including metadata and versions Expected format: { "versions": [{"version_id": str, "content": str, ...}], ...other metadata... }	required

Note

• Existing versions not included in prompt_data remain unchanged
• New versions are added
• Modified versions are completely replaced

promptsite.storage.git.GitStorage dataclass

Bases: FileStorage

Git-based storage implementation extending FileStorage.

Extends FileStorage to add Git version control capabilities. All operations are automatically committed to the Git repository and can be synced with a remote repository.

Attributes:

Name	Type	Description
remote	str	URL of the remote Git repository
branch	str	Git branch to use (defaults to "main")
auto_sync	bool	Whether to automatically sync with remote
repo	Repo	GitPython repository instance

Example

storage = GitStorage( ... base_path="/path/to/repo", ... remote="https://github.com/user/repo.git", ... branch="main", ... auto_sync=True ... )

__post_init__()

Initialize the storage.

_commit(message, files=None)

Create a git commit with the specified message and files.

Parameters:

Name	Type	Description	Default
message	str	Commit message	required
files	Optional[List[str]]	List of file paths to add to the commit	None

_ensure_repo()

Ensure git repository exists and is properly configured.

add_run(prompt_id, version_id, run_data)

Add a new run to an existing version of a prompt in the Git repository.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
version_id	str	Unique identifier for the version	required
run_data	Dict	Run data including output and metadata	required

add_version(prompt_id, version_data)

Add a new version to an existing prompt in the Git repository.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
version_data	Dict	Version data including content and metadata	required

create_prompt(prompt_id, prompt_data)

Create a new prompt in the Git repository.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
prompt_data	Dict	Prompt data including content and metadata	required

delete_prompt(prompt_id)

Delete an existing prompt from the Git repository.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required

sync()

Sync local changes with remote repository if configured.

update_prompt(prompt_id, prompt_data)

Update an existing prompt in the Git repository.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
prompt_data	Dict	Prompt data including content and metadata	required