PromptOS Python SDK

Official Python SDK for interacting with the PromptOS.dev API prompts endpoints.

Installation

pip install promptos

Quick Start

from promptos import PromptOSClient

# Initialize the client with your API key
client = PromptOSClient(api_key="mpa_live_your_api_key_here")

# List all prompts
prompts = client.prompts.list()
for prompt in prompts.data:
    print(f"{prompt.title} - {prompt.id}")

# Render a prompt
result = client.prompts.render(
    prompt_id="your_prompt_id",
    inputs={"name": "John", "topic": "Python"}
)
print(result.prompt)

Authentication

The SDK requires an API key for authentication. You can obtain an API key from your PromptOS dashboard.

API keys come in two types:

• Live keys (mpa_live_...): For production use
• Test keys (mpa_test_...): For development and testing

# Production client
client = PromptOSClient(api_key="mpa_live_...")

# Development client  
client = PromptOSClient(api_key="mpa_test_...")

Client Configuration

You can customize the client behavior:

client = PromptOSClient(
    api_key="mpa_live_...",
    base_url="http://localhost:3001",  # Custom API endpoint
    timeout=60,                        # Request timeout in seconds
    max_retries=5                      # Number of retries for failed requests
)

API Reference

Prompts

List Prompts

List all prompts in your organization with pagination support.

# Basic usage
prompts = client.prompts.list()

# With pagination
prompts = client.prompts.list(page=2, limit=50)

# Access results
for prompt in prompts.data:
    print(f"ID: {prompt.id}")
    print(f"Title: {prompt.title}")
    print(f"Tags: {prompt.tags}")
    if prompt.latest_version:
        print(f"Latest version: v{prompt.latest_version.version}")

Get Prompt Details

Retrieve detailed information about a specific prompt, including all versions.

prompt = client.prompts.get("prompt_id_here")

print(f"Prompt: {prompt.title}")
print(f"Description: {prompt.description}")
print(f"Alias: {prompt.alias}")
print(f"Number of versions: {len(prompt.versions)}")

# Access version history
for version in prompt.versions:
    print(f"Version {version.version}: {version.status}")
    print(f"Content: {version.content}")
    if version.variables:
        print(f"Variables: {version.variables}")

Render Prompt

Render a prompt with the latest published version.

# Render by ID
result = client.prompts.render(
    prompt_id="prompt_id_here",
    inputs={
        "name": "Alice",
        "product": "PromptOS",
        "feature": "SDK"
    }
)

print(result.prompt)  # The rendered prompt text
print(f"Version used: {result.metadata['version']}")
print(f"Variables used: {result.metadata['variables']}")

# Render by alias
result = client.prompts.render_by_alias(
    alias="welcome-email",
    inputs={"name": "Bob"}
)

Error Handling

The SDK provides specific exception types for different error scenarios:

from promptos import (
    PromptOSError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    ServerError
)

try:
    result = client.prompts.render("invalid_id")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    print(f"Status code: {e.status_code}")
except NotFoundError as e:
    print(f"Prompt not found: {e}")
except ValidationError as e:
    print(f"Invalid request: {e}")
    print(f"Details: {e.response}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except ServerError as e:
    print(f"Server error: {e}")
except PromptOSError as e:
    print(f"General error: {e}")

Models

The SDK uses Pydantic models for type safety and validation:

• Prompt: Basic prompt information (used in list responses)
• PromptDetail: Full prompt details including all versions
• PromptVersion: Individual version information
• PromptListResponse: Response from list endpoint with pagination
• PromptRenderResponse: Response from render endpoint

Examples

See the examples/ directory for more detailed examples:

• basic_usage.py: Basic operations
• prompt_rendering.py: Advanced rendering examples
• error_handling.py: Comprehensive error handling

Development

Running Tests

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=promptos

Type Checking

mypy promptos

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://docs.promptos.dev
• API Reference: https://api.promptos.dev
• Issues: https://github.com/promptos/python-sdk/issues