Registry / llm-agents / prompty

prompty

JSON →
library0.1.50pypypiunverified

Prompty is a new asset class and format for LLM prompts that aims to provide observability, understandability, and portability for developers. It includes a specification, tooling, and a runtime. The Python runtime (current version 0.1.50) allows developers to load, render, parse, and execute Prompty files within Python applications. It's actively developed by Microsoft, with distinct release cycles for its Python, C#, and TypeScript bindings.

pip install prompty
INSTALL
IMPORT
SIG · PROMPTY
P
prompty
llm-agentspythonv0.1.50
Install
4.9s avg
Import
482ms
Disk
77MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.50 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.503s · 77.3MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 4.9s · import 0.461s · 77MB
77MB installed
● package 77MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

prompty
import prompty
from prompty import prompty

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")
Debug
Known issues
breakingThe 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.
affects: All versions running Prompty v2 spec against v1 files.
gotchaPrompty 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.
affects: All versions.
gotchaPrompty 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.
affects: All versions.
gotchaWhile 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.
affects: <=0.1.50 (Python 3.9 users)
gotchaPrompty 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.
affects: All versions.
Upgrade
Version history
0.1.50latest on PyPI · released Apr 2, 2025
Audit
Dependencies
python>=3.9requiredMinimum Python version required by PyPI. Newer documentation often recommends Python 3.10+ or 3.11+ for full compatibility with examples and modern features.
openaioptionalRequired for OpenAI provider support (installed via `prompty[openai]`).
azure-identityoptionalRequired for Microsoft Foundry provider support (installed via `prompty[foundry]`).
jinja2optionalRequired for Jinja2 template rendering (installed via `prompty[jinja2]`).
Agent activity
23 hits · last 30 days
node
20
Amazon
1
OpenAI (training)
1
Resources
prompty — pip install prompty · libregistry