{"id":6419,"library":"prompty","title":"Prompty Python Runtime","description":"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.","status":"active","version":"0.1.50","language":"en","source_language":"en","source_url":"https://github.com/Microsoft/prompty","tags":["LLM","prompts","AI","observability","prompt engineering","Microsoft","prompt-as-code"],"install":[{"cmd":"pip install prompty","lang":"bash","label":"Core installation"},{"cmd":"pip install prompty[openai,azure,jinja2,all]","lang":"bash","label":"Installation with common extras"}],"dependencies":[{"reason":"Minimum Python version required by PyPI. Newer documentation often recommends Python 3.10+ or 3.11+ for full compatibility with examples and modern features.","package":"python>=3.9","optional":false},{"reason":"Required for OpenAI provider support (installed via `prompty[openai]`).","package":"openai","optional":true},{"reason":"Required for Microsoft Foundry provider support (installed via `prompty[foundry]`).","package":"azure-identity","optional":true},{"reason":"Required for Jinja2 template rendering (installed via `prompty[jinja2]`).","package":"jinja2","optional":true}],"imports":[{"symbol":"prompty","correct":"import prompty"},{"note":"Specific tracing components are meant to be imported directly, not via the top-level module.","wrong":"import prompty.tracer","symbol":"Tracer","correct":"from prompty.tracer import Tracer, console_tracer, PromptyTracer, trace"}],"quickstart":{"code":"import os\nimport prompty\n\n# Create a dummy .prompty file for the example\nprompty_content = \"\"\"\n---\nname: greeting\nmodel:\n  id: gpt-4o-mini\n  provider: openai\n  connection:\n    kind: key\n    apiKey: ${env:OPENAI_API_KEY}\ninputSchema:\n  properties:\n    name:\n      kind: string\n      default: World\ntemplate:\n  format:\n    kind: jinja2\n  parser:\n    kind: prompty\n---\nsystem: You are a friendly assistant.\nuser: Say hello to {{name}}.\n\"\"\"\n\nwith open(\"greeting.prompty\", \"w\") as f:\n    f.write(prompty_content)\n\n# Ensure OPENAI_API_KEY is set in your environment\n# For local testing, you might set it like this:\n# os.environ[\"OPENAI_API_KEY\"] = \"your_openai_api_key_here\"\nopenai_api_key = os.environ.get('OPENAI_API_KEY', '')\n\nif not openai_api_key:\n    print(\"Warning: OPENAI_API_KEY environment variable not set. Skipping execution.\")\n    print(\"Please set OPENAI_API_KEY for the quickstart to run successfully.\")\nelse:\n    try:\n        # One-shot: load + prepare + run\n        result = prompty.execute(\n            \"greeting.prompty\", \n            inputs={\"name\": \"Jane\"}\n        )\n        print(\"\\nPrompty execution result (one-shot):\")\n        print(result)\n\n        # Step-by-step example\n        agent = prompty.load(\"greeting.prompty\")\n        messages = prompty.prepare(\n            agent, \n            inputs={\"name\": \"World\"}\n        )\n        step_by_step_result = prompty.run(agent, messages)\n        print(\"\\nPrompty execution result (step-by-step):\")\n        print(step_by_step_result)\n    except Exception as e:\n        print(f\"\\nAn error occurred during Prompty execution: {e}\")\n        print(\"Ensure your OPENAI_API_KEY is valid and has access to gpt-4o-mini.\")\n\n# Clean up the dummy file\nos.remove(\"greeting.prompty\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions running Prompty v2 spec against v1 files."},{"fix":"Always install `prompty` with the necessary extras, for example: `pip install prompty[openai,jinja2]` or `pip install prompty[all]` for all features.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All 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.","message":"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.","severity":"gotcha","affected_versions":"<=0.1.50 (Python 3.9 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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}