Core API Reference

This page documents the core API functionality of PromptSite.

promptsite.core.PromptSite

Main class for managing prompts and their versions.

The PromptSite class provides a high-level interface for managing prompts, versions, and execution runs. It handles all operations through a configured storage backend and provides methods for prompt registration, version control, and run tracking.

Attributes:

Name	Type	Description
storage	StorageBackend	Backend storage implementation for persisting data

Example

ps = PromptSite(storage_backend) prompt = ps.register_prompt("my-prompt", "Initial content") version = ps.add_prompt_version("my-prompt", "Updated content")

prompts property

Get all prompts as a pandas DataFrame.

runs property

Get all runs as a pandas DataFrame.

versions property

Get all versions as a pandas DataFrame.

__init__(storage=None)

Initialize promptsite.

Parameters:

Name	Type	Description	Default
storage	Storage	Storage backend instance.	None

add_prompt_version(prompt_id, new_content=None, variables=None)

Add a new version to an existing prompt.

Creates a new version of the prompt with updated content. If the prompt has an associated file, the content can be read from the file instead of being provided directly.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt to version	required
new_content	Optional[str]	Optional new content for the version	None

Returns:

Name	Type	Description
Version	Version	The newly created version object

Raises:

Type	Description
PromptNotFoundError	If prompt_id doesn't exist
InvalidPromptContentError	If no content is provided

add_run(prompt_id, version_id, final_prompt, variables=None, llm_output=None, execution_time=None, llm_config=None)

Record a new execution run for a specific prompt version.

Tracks the execution of a prompt version including the LLM's response, execution metrics, and configuration used.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
version_id	str	ID of the version executed	required
llm_output	Optional[str]	Output received from the LLM	None
execution_time	Optional[float]	Time taken for execution in seconds	None
llm_config	Optional[Dict[str, Any]]	Configuration used for the LLM call	None

Returns:

Name	Type	Description
Run	Run	The created run object

Raises:

Type	Description
PromptNotFoundError	If prompt doesn't exist
VersionNotFoundError	If version doesn't exist

delete_prompt(prompt_id)

Delete a prompt and its associated file data.

Parameters:

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

Raises:

Type	Description
PromptNotFoundError	If prompt with given ID doesn't exist

get_last_run(prompt_id)

Get the last run of a specific prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required

Returns:

Name	Type	Description
Run	Run	The last run of the prompt

get_prompt(prompt_id, exclude_versions=False)

Get a prompt by its id.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt to retrieve	required
exclude_versions	bool	Whether to exclude versions from the prompt	False

Returns:

Name	Type	Description
Prompt	Prompt	The requested prompt

Raises:

Type	Description
PromptNotFoundError	If prompt with given ID doesn't exist

get_run(prompt_id, version_id, run_id)

Get a specific run of a prompt version.

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
Run	Run	The requested run

Raises:

Type	Description
PromptNotFoundError	If prompt doesn't exist
RunNotFoundError	If run doesn't exist

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 to retrieve	required

Returns:

Name	Type	Description
Version	Version	The requested version

Raises:

Type	Description
PromptNotFoundError	If prompt doesn't exist
VersionNotFoundError	If version doesn't exist

get_version_by_content(prompt_id, content)

Get a version by its content.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required
content	str	Content to search for	required

Returns:

Name	Type	Description
Version	Optional[Version]	The version with matching content
None	Optional[Version]	If no version matches the content

list_prompts(exclude_versions=False)

Get all registered prompts.

Returns:

Type	Description
List[Prompt]	List[Prompt]: List of all prompts

list_runs(prompt_id, version_id)

Get all runs for a specific prompt version.

Parameters:

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

Returns:

Type	Description
List[Run]	List[Run]: List of all runs for the version

list_versions(prompt_id, exclude_runs=False)

Get all versions of a prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt	required

Returns:

Type	Description
List[Version]	List[Version]: List of all versions

Raises:

Type	Description
PromptNotFoundError	If prompt with given ID doesn't exist

register_prompt(prompt_id, description='', tags=None, initial_content=None, variables=None)

Register a new prompt with the system.

Creates a new prompt entry with optional file association and initial content. The prompt can be created either from direct content or from a file.

Parameters:

Name	Type	Description	Default
prompt_id	str	Unique identifier for the prompt	required
description	str	Optional description of the prompt's purpose	''
tags	Optional[List[str]]	Optional list of tags for categorization	None
initial_content	Optional[str]	Optional initial content	None
variables	Optional[Dict[str, Variable]]	Optional variables for the prompt	None

Returns: Prompt: The newly created prompt object

Raises:

Type	Description
PromptAlreadyExistsError	If prompt_id already exists

sync_git()

Synchronize changes with git remote if storage backend supports it.

Raises:

Type	Description
StorageError	If storage backend doesn't support git operations
StorageError	If sync operation fails

update_prompt(prompt_id, **kwargs)

Update the variables of a prompt.

Parameters:

Name	Type	Description	Default
prompt_id	str	ID of the prompt to update	required
kwargs		Optional fields to update	{}