Prompt Orchestration Markup Language

POML is a structured markup language designed for advanced prompt engineering for Large Language Models (LLMs). It uses an HTML-like syntax to organize prompt components, making them modular, reusable, and maintainable.

Key capabilities include:

• Structured Prompting: Uses semantic components like <role>, <task>, and <example>.
• Data Integration: Specialized tags like <document>, <table, and <img for embedding external data.
• Decoupled Styling: A CSS-like system to separate prompt content from presentation (e.g., verbosity or syntax format) via <stylesheet> or inline attributes.
• Templating Engine: Supports variables ({{ }}), loops (for), conditionals (if), and variable definitions (<let>).

POML supports 'meta-like' components that affect prompt rendering and LLM execution without appearing in the final prompt messages. These components are used for configuration that should be invisible to the LLM but functional for the runtime. Examples include:

• <stylesheet>
• <output-schema>
• <tool-definition>
• <runtime>

To get started with POML, create a file with a .poml extension (e.g., example.poml). A standard POML file uses an XML-like structure to define a role, a task, optional media assets (like <img>), and an output-format. Ensure any referenced local assets, such as images, are in the same directory as the .poml file.

<poml>
  <role>You are a patient teacher explaining concepts to a 10-year-old.</role>
  <task>Explain the concept of photosynthesis using the provided image as a reference.</task>

  <img src="photosynthesis_diagram.png" alt="Diagram of photosynthesis" />

  <output-format>
    Keep the explanation simple, engaging, and under 100 words.
    Start with "Hey there, future scientist!".
  </output-format>
</poml>

The whiteSpace attribute controls whitespace handling when rendering to the Intermediate Representation (IR). However, when converting the IR to specific formats like Markdown, JSON, or XML, the target format's syntax rules may still affect the output.

To ensure whitespace is kept exactly as intended, use syntax="text" combined with whiteSpace="pre". Note that when using syntax="text", you cannot use nested tags like <p> within the content.

<poml syntax="text" whiteSpace="pre">

To use the MLflow integration, install POML with the agent extra via pip. Alternatively, you can install the required MLflow components separately.

pip install poml[agent]

Or:

pip install mlflow mlflow-genai

The full implementation of the Travel Expense Agent workflow is provided in the repository examples. You can run the complete Python script to see the end-to-end process of document extraction, rule identification, compliance checking, and email generation.

python 404_travel_expense_agent.py

To install the latest nightly build of the POML Python SDK, use the following command which points to the test PyPI index.

pip install --upgrade --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ poml

To capture a comprehensive audit trail of every interaction with the LLM, enable tracing in your Python application using poml.set_trace(). This creates a directory containing the POML source, context variables, rendered outputs, and environment metadata (the "crime scene").

Note: It is recommended to add the specified trace directory to your .gitignore to avoid committing trace data to version control.

import poml

# Enable tracing for all POML calls
poml.set_trace(trace_dir="pomlruns")

To iterate over a list, use the for attribute with the syntax for="itemName in listName".

Inside the loop, you have access to the loop object:

• loop.index: Current iteration index (starts at 0).
• loop.length: Total number of items.
• loop.first: true if it's the first item.
• loop.last: true if it's the last item.

<poml>
  <list>
    <item for="item in ['apple', 'banana', 'cherry']">{{item}}</item>
  </list>
</poml>