Executing Prompts

Basic Usage

Execute a prompt using its key:

from switchport import Switchport

client = Switchport()

response = client.prompts.execute(
    prompt_key="welcome-message"
)

print(response.text)

Using Variables

Pass dynamic variables to your prompts:

response = client.prompts.execute(
    prompt_key="welcome-message",
    variables={
        "name": "Alice",
        "product": "Pro Plan"
    }
)

Your prompt template in the dashboard:

Write a friendly welcome message for {{name}} who just purchased {{product}}.

Using Subject for A/B Testing

Provide a subject to enable deterministic A/B testing:

response = client.prompts.execute(
    prompt_key="product-pitch",
    subject={"user_id": "user_123"},
    variables={"product": "Enterprise Plan"}
)

print(f"Version: {response.version_name}")

The same subject always gets the same version. This ensures users have a consistent experience.

Subject Types

Subject can be either a string or a dictionary:

response = client.prompts.execute(
    prompt_key="greeting",
    subject="user_123"
)

response = client.prompts.execute(
    prompt_key="greeting",
    subject={
        "user_id": "user_123",
        "tier": "premium",
        "region": "us-west"
    }
)

Response Object

The execute method returns a response object with the following attributes:

response = client.prompts.execute(
    prompt_key="welcome-message",
    variables={"name": "Alice"}
)

# Generated text from the LLM
print(response.text)

# Model that was used
print(response.model)  # e.g., "gpt-5"

# Version that was selected
print(response.version_name)  # e.g., "v1"
print(response.version_id)    # e.g., "ver_abc123"

# Unique request identifier
print(response.request_id)  # e.g., "req_xyz789"

Response Attributes

Attribute	Type	Description
`text`	`str`	The generated text from the LLM
`model`	`str`	The model used (e.g., `gpt-5`, `claude-3-5-sonnet-20241022`)
`version_name`	`str`	Human-readable version name
`version_id`	`str`	Unique version identifier
`request_id`	`str`	Unique request identifier

Error Handling

Handle common errors when executing prompts:

from switchport import (
    Switchport,
    PromptNotFoundError,
    AuthenticationError,
    APIError
)

client = Switchport()

try:
    response = client.prompts.execute(
        prompt_key="my-prompt",
        variables={"name": "Alice"}
    )
    print(response.text)

except PromptNotFoundError:
    print("Prompt not found - check your prompt key")

except AuthenticationError:
    print("Authentication failed - check your API key")

except APIError as e:
    print(f"API error: {e}")
    # Fallback to default behavior

Common Patterns

Pattern 1: Dynamic Email Generation

def send_welcome_email(user):
    response = client.prompts.execute(
        prompt_key="welcome-email",
        subject={"user_id": user.id},
        variables={
            "name": user.name,
            "email": user.email
        }
    )

    send_email(user.email, response.text)

Pattern 2: Chatbot Responses

def get_bot_response(user_id, user_message):
    response = client.prompts.execute(
        prompt_key="support-bot",
        subject={"user_id": user_id},
        variables={
            "user_message": user_message,
            "conversation_history": get_history(user_id)
        }
    )

    return response.text

Pattern 3: Content Generation

def generate_product_description(product_id, user_segment):
    product = get_product(product_id)

    response = client.prompts.execute(
        prompt_key="product-description",
        subject={"segment": user_segment},
        variables={
            "product_name": product.name,
            "features": product.features,
            "price": product.price
        }
    )

    return response.text

Pattern 4: Fallback Handling

def get_ai_response(prompt_key, variables):
    try:
        response = client.prompts.execute(
            prompt_key=prompt_key,
            variables=variables
        )
        return response.text

    except APIError:
        # Fallback to default template if API fails
        return get_default_response(prompt_key, variables)

Best Practices

Always use subject identification for A/B testing

If you want to track metrics or run A/B tests, always provide subject identification when executing prompts.

Use consistent subject

Use the same subject (e.g., user ID) across prompt executions and metric recording for the same user or session.

Handle errors gracefully

Always implement error handling with fallback behavior to ensure your application continues working even if the API fails.

Cache responses when appropriate

For expensive or frequently-used prompts, consider caching responses to reduce API calls and latency.

Log request IDs

Store request_id values for debugging and support purposes.

Next Steps

Recording Metrics

Learn how to track metrics for your prompts

A/B Testing

Set up A/B tests with multiple versions

Getting Started

Core Features

Examples

Basic Usage

Using Variables

Using Subject for A/B Testing

Subject Types

Response Object

Response Attributes

Error Handling

Common Patterns

Pattern 1: Dynamic Email Generation

Pattern 2: Chatbot Responses

Pattern 3: Content Generation

Pattern 4: Fallback Handling

Best Practices

Next Steps

Recording Metrics

A/B Testing

​Basic Usage

​Using Variables

​Using Subject for A/B Testing

​Subject Types

​Response Object

​Response Attributes

​Error Handling

​Common Patterns

​Pattern 1: Dynamic Email Generation

​Pattern 2: Chatbot Responses

​Pattern 3: Content Generation

​Pattern 4: Fallback Handling

​Best Practices

​Next Steps

Recording Metrics

A/B Testing

Basic Usage

Using Variables

Using Subject for A/B Testing

Subject Types

Response Object

Response Attributes

Error Handling

Common Patterns

Pattern 1: Dynamic Email Generation

Pattern 2: Chatbot Responses

Pattern 3: Content Generation

Pattern 4: Fallback Handling

Best Practices

Next Steps