prompt

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.