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 Splunk AO prompts. This class provides an intuitive way to work with Splunk AO 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

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 SPLUNK_AO_PROJECT_ID or SPLUNK_AO_PROJECT env vars. Examples prompt = Prompt(name=“test”, messages=[…]).create() assert prompt.is_synced()

​
create_version

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

Delete this prompt. Examples prompt = Prompt.get(name=“ml-expert-v1”) prompt.delete()

​
get

Get an existing prompt by ID or name. Arguments
  • id (Optional[str]): The prompt ID.
  • name (Optional[str]): The prompt name.

​
list

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

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

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

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

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

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.