> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galileo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```python theme={null}
# 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

```python theme={null}
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**

```python theme={null}
prompt = Prompt(name="test", messages=[...]).create()
assert prompt.is_synced()
```

### create\_version

```python theme={null}
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

```python theme={null}
def delete(self) -> None
```

Delete this prompt.

**Examples**

```python theme={null}
prompt = Prompt.get(name="ml-expert-v1")
prompt.delete()
```

### get

```python theme={null}
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

```python theme={null}
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

```python theme={null}
def list_versions(self) -> builtins.list[PromptVersion]
```

List all versions of this prompt template.

**Examples**

```python theme={null}
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

```python theme={null}
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**

```python theme={null}
prompt.refresh()
assert prompt.is_synced()
```

### save

```python theme={null}
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**

```python theme={null}
# 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

```python theme={null}
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

```python theme={null}
def update(self, *, name: str) -> Prompt
```

Update this prompt's name.

**Examples**

```python theme={null}
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.
```