Skip to main content

​
PromptVersion

Represents a single version of a prompt template.

​
Attributes

id (str): The unique version identifier. version (int): The version number (1-indexed). messages (list[Message]): The prompt messages for this version. settings (PromptRunSettings | None): The prompt run settings. created_at (datetime | None): When the version was created. updated_at (datetime | None): When the version was last updated.

​
Prompt

Object-centric interface for Galileo prompts. This class provides an intuitive way to work with Galileo prompts, encapsulating prompt management operations including version management. Arguments
  • Known Limitations:
  • -----------------: Project Association: The API response schema (BasePromptTemplateResponse) does not include project association information. Therefore, project_id and project_name will only be populated for prompts created in the current session via create(). Prompts retrieved via get() or list() will have these attributes set to None, even if they were originally created with a project association.
Examples 
# Create a new prompt locally, then persist
prompt = Prompt(
    name="ml-expert-v1",
    messages=[
        Message(role=MessageRole.system, content="You are an expert in ML."),
        Message(role=MessageRole.user, content="{{input}}"),
    ],
).create()

# Create a prompt associated with a project
prompt = Prompt(
    name="ml-expert-v1",
    messages=[...],
    project_name="My Project",
).create()

# Get an existing prompt
prompt = Prompt.get(name="ml-expert-v1")

# Create a new version with updated messages
prompt.create_version(messages=[...])

# List all versions
versions = prompt.list_versions()

# Select a specific version
prompt.select_version(2)

# Update prompt name only (use create_version for content changes)
prompt.update(name="ml-expert-v2")

# Delete a prompt
prompt.delete()

​
create

def create(self) -> Prompt
Persist this prompt to the API. If project_id or project_name is set, associates the prompt with that project. If neither is set, falls back to GALILEO_PROJECT_ID or GALILEO_PROJECT env vars. Examples 
prompt = Prompt(name="test", messages=[...]).create()
assert prompt.is_synced()

​
create_version

def create_version(self, messages: builtins.list[Message] | None=None) -> Prompt
Create a new version of this prompt template. This creates an actual new version in the prompt’s version history, not a separate prompt. The new version becomes the selected version. Arguments
  • messages (Optional[list[Message]]): Messages for the new version. If not provided, uses the current messages.

​
delete

def delete(self) -> None
Delete this prompt. Examples 
prompt = Prompt.get(name="ml-expert-v1")
prompt.delete()

​
get

def get(cls, *, id: str | None=None, name: str | None=None) -> Prompt | None
Get an existing prompt by ID or name. Arguments
  • id (Optional[str]): The prompt ID.
  • name (Optional[str]): The prompt name.

​
list

def list(cls,
         *,
         name_filter: str | None=None,
         limit: Unset | int=100,
         project_id: str | None=None,
         project_name: str | None=None) -> list[Prompt]
List global prompt templates with optional filtering. Arguments
  • name_filter (Optional[str]): Filter prompts by name containing this string.
  • limit (Union[Unset, int]): Maximum number of prompts to return.
  • project_id (Optional[str]): Filter prompts used in this project by ID.
  • project_name (Optional[str]): Filter prompts used in this project by name.

​
list_versions

def list_versions(self) -> builtins.list[PromptVersion]
List all versions of this prompt template. Examples 
prompt = Prompt.get(name="ml-expert-v1")
versions = prompt.list_versions()
for v in versions:
    print(f"Version {v.version}: {len(v.messages)} messages")

**Notes**

This method returns ``PromptVersion`` objects instead of ``Prompt`` objects
    to avoid an N+1 API call problem. Each version's full prompt data would require
    a separate API call. To work with a specific version, use
    ``select_version(version_number)`` which selects the version and updates
    the prompt's messages and version attributes.

​
refresh

def refresh(self) -> None
Refresh this prompt’s state from the API. Updates all attributes with the latest values from the remote API and sets the state to SYNCED. Examples 
prompt.refresh()
assert prompt.is_synced()

​
save

def save(self) -> Prompt
Save this prompt to the API. Behavior depends on the prompt’s current state:
  • LOCAL_ONLY: Creates the prompt via create()
  • SYNCED: No action needed, already saved
  • DIRTY: Persists pending field changes via update()
  • FAILED_SYNC: Raises ValueError — use refresh() to recover or retry the original operation
  • DELETED: Raises ValueError
For updating an existing prompt’s messages, use create_version(messages=[…]) instead. Examples 
# Create and save a new prompt
prompt = Prompt(name="my-prompt", messages=[...])
prompt.save()  # Creates the prompt

# Mutate a field and persist the change
prompt = Prompt.get(name="my-prompt")
prompt.name = "renamed-prompt"  # Transitions to DIRTY
prompt.save()  # Persists the rename via update()

​
select_version

def select_version(self, version: int) -> Prompt
Set a specific version as the selected/active version. This updates the prompt’s selected version, and the messages will be updated to reflect the content of the selected version. Arguments
  • version (int): The version number to select (1-indexed).

​
update

def update(self, *, name: str) -> Prompt
Update this prompt’s name. Examples 
prompt = Prompt.get(name="ml-expert-v1")
prompt.update(name="ml-expert-v2")

# To update messages, use create_version() instead:
prompt.create_version(messages=[
    Message(role=MessageRole.system, content="Updated system message"),
    Message(role=MessageRole.user, content="{{input}}"),
])

**Notes**

The API only supports updating the prompt name. To update messages,
    use ``create_version()`` which creates a new immutable version.
    This design ensures traceability and allows rollback to previous versions.

Args:
    name (str): New name for the prompt.