readprompt

The server-side Python SDK for executing published ReadPrompt prompts.

This package sends an execution API key. Use it only in trusted server-side, worker, or serverless code. Do not include it in browser code, mobile apps, or client-side analytics.

Install

pip install readprompt

Requires Python 3.10 or later.

Synchronous client

import os

from readprompt import ReadPrompt

with ReadPrompt(api_key=os.environ["READPROMPT_EXECUTION_API_KEY"]) as readprompt:
    result = readprompt.execute(
        "product-answer",
        {"question": "What is ReadPrompt?"},
    )

print(result.data["answer"])
print(result.meta.resolved_model)

The returned data exactly matches the published prompt version's output schema. Its shape is prompt-specific, so do not assume an answer field universally.

Execute by ID

result = readprompt.execute_by_id(
    "13ededb4-7e14-49b0-bc3c-729ad6e04f7b",
    {"question": "What is ReadPrompt?"},
)

Async client and streaming

import os

from readprompt import AsyncReadPrompt, ReadPromptStreamError


async def main() -> None:
    try:
        async with AsyncReadPrompt(api_key=os.environ["READPROMPT_EXECUTION_API_KEY"]) as readprompt:
            async for event in readprompt.stream(
                "product-answer",
                {"question": "What is ReadPrompt?"},
            ):
                if event.type == "delta":
                    print(event.text, end="", flush=True)
                else:
                    print("\nValidated output:", event.result.data)
    except ReadPromptStreamError as error:
        print(error.code, error)
        raise

Only the terminal complete event carries schema-validated application data. delta text is partial model output and may be incomplete JSON. A terminal SSE error becomes ReadPromptStreamError.

Errors

from readprompt import ReadPromptApiError

try:
    result = readprompt.execute("product-answer", {"question": "Hello"})
except ReadPromptApiError as error:
    if error.status_code == 429:
        print(f"Retry after {error.retry_after_seconds or 'a short delay'} seconds.")
    raise

The SDK does not automatically retry executions: a retry may duplicate model work or cost. Handle retries in your application only when repeating the operation is safe.

Configuration

The default Executor base URL is https://sdk.readprompt.dev/v1. For local development or tests:

readprompt = ReadPrompt(
    api_key=os.environ["READPROMPT_EXECUTION_API_KEY"],
    base_url="http://127.0.0.1:8000/v1",
)

See the ReadPrompt application documentation for prompt publishing, variable schemas, output schemas, API-key lifecycle, routing, and rate limits.