Quickstart with Python

This quickstart mirrors the Node.js quickstart for the Python SDK. By the end you will have a working call against a published prompt, an async streaming example, and a checklist for production use.

1. 1

   Generate an API token

   Open Settings → API tokens in the dashboard, click New token, name it (e.g. local-dev-python), and copy the value immediately. Tokens are revealed exactly once.

   Export the token in your shell or store it in a .env file loaded by python-dotenv:

   PROMPTHELM_API_KEY=ph_live_your_token_here

2. 2

   Install the SDK

   Until the PyPI release lands, install from GitHub:

   pippoetryuv

   pip install "git+https://github.com/Runivox/prompt-helm-sdk-python.git"

   When the PyPI release ships you will be able to install it with the familiar pip install prompt-helm.

3. 3

   Create your first prompt

   In the dashboard, go to Prompts → New prompt. Give it a slug (support-triage is a fine example), pick a default model, and use {{ variable_name }} for runtime variables. Saving publishes v1 on the main environment.

   Learn more

   See Concepts → Prompts for versions, environments, and promotion semantics.

4. 4

   Call it from Python (sync)

   The synchronous client is the simplest entry point. It picks up PROMPTHELM_API_KEY from the environment.

   from prompt_helm import PromptHelm
   
   client = PromptHelm(
       # api_key defaults to os.environ["PROMPTHELM_API_KEY"].
       # Pass it explicitly only when reading from a secrets manager.
   )
   
   result = client.execute(
       prompt_slug="support-triage",
       environment="main",
       variables={"ticket": "Password reset email never arrived."},
   )
   
   print("Response:", result.output)
   print("Cost (USD):", result.usage.cost_usd)
   print("Latency (ms):", result.metrics.latency_ms)

   Run it:

   python quickstart.py

   The call appears in the dashboard's Logs view with the full request/response payload, the per-call cost, and the round-trip latency.

5. 5

   Stream the response (async)

   For server-side streaming endpoints, use the asynchronous client. It exposes an AsyncIterator that yields typed chunks.

   import asyncio
   from prompt_helm import AsyncPromptHelm
   
   client = AsyncPromptHelm()
   
   async def main() -> None:
       async with client.stream(
           prompt_slug="support-triage",
           environment="main",
           variables={"ticket": "How do I rotate my API key?"},
       ) as stream:
           async for chunk in stream:
               if chunk.type == "delta":
                   print(chunk.text, end="", flush=True)
               elif chunk.type == "done":
                   print()
                   print("Cost (USD):", chunk.usage.cost_usd)
   
   asyncio.run(main())

   Streaming uses Server-Sent Events under the hood and integrates cleanly with fastapi and starlette response types.

6. 6

   Ship to production

   Before pointing real traffic at PromptHelm:

   • Read the token from a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault, or whatever you already use). Never commit it.
   • Catch typed errors. The SDK exposes PromptHelmError with a stable code attribute — map well-known codes to retries or user-facing messages.
   • Set a request timeout. Pass timeout=15.0 (seconds) on the client constructor or per-call to bound a slow provider.
   • Pin an environment. Promote prompt versions from dev to staging to main before they touch production traffic.
   • Tag your traffic. Pass metadata={"tenant_id": ..., "feature": ...} so the cost dashboard slices align with your product surfaces.

Next steps