Prompts#

class Prompts(client, *, _guard=None)#

Bases: object

Provides methods for interacting with prompt resources.

This class allows you to retrieve and create prompt versions.

Examples

Basic prompt operations:

from phoenix.client import Client
client = Client()

# Get the latest version of a prompt
prompt_version = client.prompts.get(prompt_identifier="my-prompt")
print(f"Prompt template: {prompt_version.template}")

# Get a specific version by ID
specific_version = client.prompts.get(prompt_version_id="version-123")
print(f"Model: {specific_version.model_name}")

# Get a tagged version
production_version = client.prompts.get(
    prompt_identifier="my-prompt",
    tag="production"
)

# Create a new prompt version
from phoenix.client.types.prompts import PromptVersion
new_version = client.prompts.create(
    name="sentiment-classifier",
    version=PromptVersion(
        template="Classify the sentiment: {{text}}",
        model_name="gpt-4",
        model_provider="OPENAI"
    ),
    prompt_description="Sentiment classification prompt",
    metadata={"category": "classification", "version": "1.0"}
)

Working with tags:

# List all tags for a prompt version
tags = client.prompts.tags.list(prompt_version_id="version-123")
for tag in tags:
    print(f"Tag: {tag['name']}")

# Create a new tag
client.prompts.tags.create(
    prompt_version_id="version-123",
    name="staging",
    description="Ready for staging deployment"
)
create(*, version, name, prompt_description=None, prompt_metadata=None)#

Creates a new version for the prompt under the name specified. The prompt will be created if it doesn’t already exist.

Parameters:

  • version (v1.PromptVersion) – The version of the prompt to create.

  • name (str) – The identifier for the prompt. It can contain alphanumeric characters, hyphens and underscores, but must begin with an alphanumeric character.

  • prompt_description (Optional[str]) – An optional description for the prompt. If prompt already exists, this value is ignored by the server.

  • prompt_metadata (Optional[dict[str, Any]]) – An optional metadata dictionary for the prompt. If prompt already exists, this value is ignored by the server.

Returns:

The created prompt version data.

Return type:

PromptVersion

get(*, prompt_version_id=None, prompt_identifier=None, tag=None)#

Retrieves a specific version of a prompt based on the provided identifiers.

Parameters:

  • prompt_version_id (Optional[str]) – The unique identifier for the prompt version.

  • prompt_identifier (Optional[str]) – The unique identifier for the prompt.

  • tag (Optional[str]) – An optional tag to filter the prompt version.

Returns:

The retrieved prompt version data.

Return type:

PromptVersion

Raises:

  • ValueError – If prompt identifier or prompt version id is not found.

  • httpx.HTTPStatusError – If the HTTP request returned an unsuccessful status code.

Example:

from phoenix.client import Client
client = Client()

# Get latest version of a prompt
prompt_version = client.prompts.get(prompt_identifier="my-prompt")
print(f"Template: {prompt_version.template}")

# Get specific version by ID
specific_version = client.prompts.get(prompt_version_id="version-123")

# Get tagged version
tagged_version = client.prompts.get(
    prompt_identifier="my-prompt",
    tag="production"
)
property tags#
class AsyncPrompts(client, *, _guard=None)#

Bases: object

Provides asynchronous methods for interacting with prompt resources.

This class allows you to retrieve and create prompt versions asynchronously.

Examples

Basic prompt operations:

from phoenix.client import AsyncClient
async_client = AsyncClient()

# Get the latest version of a prompt
prompt_version = await async_client.prompts.get(prompt_identifier="my-prompt")
print(f"Prompt template: {prompt_version.template}")

# Get a specific version by ID
specific_version = await async_client.prompts.get(prompt_version_id="version-123")
print(f"Model: {specific_version.model_name}")

# Get a tagged version
production_version = await async_client.prompts.get(
    prompt_identifier="my-prompt",
    tag="production"
)

# Create a new prompt version
from phoenix.client.types.prompts import PromptVersion
new_version = await async_client.prompts.create(
    name="sentiment-classifier",
    version=PromptVersion(
        template="Classify the sentiment: {{text}}",
        model_name="gpt-4",
        model_provider="OPENAI"
    ),
    prompt_description="Sentiment classification prompt",
    prompt_metadata={"category": "classification"}
)

Working with tags:

# List all tags for a prompt version
tags = await async_client.prompts.tags.list(prompt_version_id="version-123")
for tag in tags:
    print(f"Tag: {tag['name']}")

# Create a new tag
await async_client.prompts.tags.create(
    prompt_version_id="version-123",
    name="staging",
    description="Ready for staging deployment"
)
async create(*, version, name, prompt_description=None, prompt_metadata=None)#

Creates a new version for the prompt under the name specified. The prompt will be created if it doesn’t already exist.

Parameters:

  • version (v1.PromptVersion) – The version of the prompt to create.

  • name (str) – The identifier for the prompt. It can contain alphanumeric characters, hyphens and underscores, but must begin with an alphanumeric character.

  • prompt_description (Optional[str]) – An optional description for the prompt. If prompt already exists, this value is ignored by the server.

  • prompt_metadata (Optional[dict[str, Any]]) – An optional metadata dictionary for the prompt. If prompt already exists, this value is ignored by the server.

Returns:

The created prompt version data.

Return type:

PromptVersion

async get(*, prompt_version_id=None, prompt_identifier=None, tag=None)#

Retrieves a specific version of a prompt based on the provided identifiers.

Parameters:

  • prompt_version_id (Optional[str]) – The unique identifier for the prompt version.

  • prompt_identifier (Optional[str]) – The unique identifier for the prompt.

  • tag (Optional[str]) – An optional tag to filter the prompt version.

Returns:

The retrieved prompt version data.

Return type:

PromptVersion

Raises:

  • ValueError – If prompt identifier or prompt version id is not found.

  • httpx.HTTPStatusError – If the HTTP request returned an unsuccessful status code.

Example:

from phoenix.client import AsyncClient
async_client = AsyncClient()

# Get latest version of a prompt
prompt_version = await async_client.prompts.get(prompt_identifier="my-prompt")
print(f"Template: {prompt_version.template}")

# Get specific version by ID
specific_version = await async_client.prompts.get(prompt_version_id="version-123")

# Get tagged version
tagged_version = await async_client.prompts.get(
    prompt_identifier="my-prompt",
    tag="production"
)
property tags#