Prompty Python Runtime

Warnings

• breaking The Prompty specification evolved from v1 to v2, introducing changes in metadata structure. For example, `model.configuration` became `model.connection`, `model.parameters` became `model.options`, and `inputs` moved to `inputSchema.properties`. While Prompty v2 aims for backward compatibility by migrating v1 files, be aware of these structural changes when working with older `.prompty` assets.
  Fix: Review and update older `.prompty` files to align with the v2 specification, or ensure your runtime correctly handles the automatic migration (which may issue deprecation warnings). Refer to the official Prompty specification for the latest format details.
• gotcha Prompty relies on specific 'extra' installations for different LLM providers (e.g., `[openai]` for OpenAI, `[azure]` for Azure OpenAI) and template engines (e.g., `[jinja2]`). Forgetting to install these can lead to `ImportError` or `ModuleNotFoundError` at runtime when trying to use a particular provider or templating feature.
  Fix: Always install `prompty` with the necessary extras, for example: `pip install prompty[openai,jinja2]` or `pip install prompty[all]` for all features.
• gotcha Prompty files frequently use environment variables (e.g., `${env:OPENAI_API_KEY}`, `${env:AZURE_OPENAI_ENDPOINT}`) for model connection and API keys. If these environment variables are not correctly set in the execution environment, the Prompty runtime will fail to authenticate or connect to the LLM, leading to runtime errors.
  Fix: Ensure all required environment variables specified in your `.prompty` files are properly set in the shell or application environment before execution. Consider using `python-dotenv` for local development.
• gotcha While PyPI states `requires_python>=3.9`, the official documentation and code guidelines often recommend Python 3.10 or higher (and sometimes specifically 3.11 for modern syntax). Using Python 3.9 might limit access to newer features or cause unexpected behavior with examples written for later Python versions.
  Fix: Preferably use Python 3.10 or a newer version (e.g., 3.11+) to ensure full compatibility with the latest Prompty documentation and features. Check the Prompty GitHub repository's `RELEASING.md` for current test matrix details.
• gotcha Prompty is designed with a strong integration with a VS Code extension for authoring, debugging, and testing `.prompty` files. While the Python runtime can execute `.prompty` files independently, relying solely on the runtime without the VS Code extension can make the initial prompt engineering and debugging process less efficient for some users.
  Fix: For an optimized prompt engineering workflow, consider installing the Prompty VS Code extension alongside the Python runtime. This provides a rich IDE experience with features like syntax highlighting, live preview, and integrated tracing.

Install

• pip install prompty Core installation
• pip install prompty[openai,azure,jinja2,all] Installation with common extras

Imports

• prompty

  import prompty

• Tracer

  from prompty.tracer import Tracer, console_tracer, PromptyTracer, trace

  Specific tracing components are meant to be imported directly, not via the top-level module.

Quickstart

This quickstart demonstrates how to create a `.prompty` file and execute it using the `prompty.execute` function for a one-shot operation, or `prompty.load`, `prompty.prepare`, and `prompty.run` for a step-by-step pipeline. It uses an OpenAI model and requires the `OPENAI_API_KEY` environment variable to be set.

import os
import prompty

# Create a dummy .prompty file for the example
prompty_content = """
---
name: greeting
model:
  id: gpt-4o-mini
  provider: openai
  connection:
    kind: key
    apiKey: ${env:OPENAI_API_KEY}
inputSchema:
  properties:
    name:
      kind: string
      default: World
template:
  format:
    kind: jinja2
  parser:
    kind: prompty
---
system: You are a friendly assistant.
user: Say hello to {{name}}.
"""

with open("greeting.prompty", "w") as f:
    f.write(prompty_content)

# Ensure OPENAI_API_KEY is set in your environment
# For local testing, you might set it like this:
# os.environ["OPENAI_API_KEY"] = "your_openai_api_key_here"
openai_api_key = os.environ.get('OPENAI_API_KEY', '')

if not openai_api_key:
    print("Warning: OPENAI_API_KEY environment variable not set. Skipping execution.")
    print("Please set OPENAI_API_KEY for the quickstart to run successfully.")
else:
    try:
        # One-shot: load + prepare + run
        result = prompty.execute(
            "greeting.prompty", 
            inputs={"name": "Jane"}
        )
        print("\nPrompty execution result (one-shot):")
        print(result)

        # Step-by-step example
        agent = prompty.load("greeting.prompty")
        messages = prompty.prepare(
            agent, 
            inputs={"name": "World"}
        )
        step_by_step_result = prompty.run(agent, messages)
        print("\nPrompty execution result (step-by-step):")
        print(step_by_step_result)
    except Exception as e:
        print(f"\nAn error occurred during Prompty execution: {e}")
        print("Ensure your OPENAI_API_KEY is valid and has access to gpt-4o-mini.")

# Clean up the dummy file
os.remove("greeting.prompty")