poml 0.0.1

data/bin/poml

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'json'
+require_relative '../lib/poml'
+
+options = {
+  format: 'dict',
+  context: {},
+  chat: true,
+  stylesheet: nil
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: poml [options] file_or_markup"
+
+  opts.on("-f", "--format FORMAT", "Output format (raw, dict, openai_chat, langchain, pydantic)") do |f|
+    options[:format] = f
+  end
+
+  opts.on("-c", "--context JSON", "Context variables as JSON") do |c|
+    options[:context] = JSON.parse(c)
+  end
+
+  opts.on("--no-chat", "Disable chat mode") do
+    options[:chat] = false
+  end
+
+  opts.on("-s", "--stylesheet JSON", "Stylesheet as JSON") do |s|
+    options[:stylesheet] = s
+  end
+
+  opts.on("-o", "--output FILE", "Output file") do |o|
+    options[:output_file] = o
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts Poml::VERSION
+    exit
+  end
+end.parse!
+
+if ARGV.empty?
+  puts "Error: Please provide a POML file or markup string"
+  exit 1
+end
+
+markup = ARGV[0]
+
+begin
+  result = Poml.process(
+    markup: markup,
+    context: options[:context],
+    stylesheet: options[:stylesheet],
+    chat: options[:chat],
+    output_file: options[:output_file],
+    format: options[:format]
+  )
+
+  if options[:output_file]
+    puts "Output written to #{options[:output_file]}"
+  else
+    case options[:format]
+    when 'dict', 'langchain', 'pydantic'
+      puts JSON.pretty_generate(result)
+    when 'openai_chat'
+      puts JSON.pretty_generate(result)
+    else
+      puts result
+    end
+  end
+rescue => e
+  puts "Error: #{e.message}"
+  exit 1
+end

data/examples/101_explain_character.poml

@@ -0,0 +1,30 @@
+<!-- POML should always start with a POML tag to harvest most of its features. -->
+<poml>
+  <role>You are a teacher explaining figures to kids.</role>
+  <!-- Use components like role and task to help you organize your intentions. This also usually comes with better LLM performance. -->
+  <task>Please describe the figure first and then provide background knowledge to help kids understand the figure.</task>
+  <output-format>Please write your response in a friendly tone.</output-format>
+
+  <!-- Use properties like captionStyle and caption to customize your prompt style. -->
+  <hint captionStyle="header" caption="Background Knowledge">
+    <!-- Document can be used to import a word document, a PDF or a pure text. -->
+    <Document src="assets/101_tom_and_jerry.docx"/>
+  </hint>
+
+  <!-- Organize few-shot examples with example. This will automatically generates an interaction of human and AI messages. -->
+  <example>
+    <input>
+      <!-- alt strings help models without vision capabilities to understand the images. -->
+      <!-- Specify syntax = "multimedia" to send the image itself to the prompt. -->
+      <img src="assets/101_tom_cat.jpg" alt="The image contains the Tom cat character." syntax="multimedia" />
+    </input>
+    <output>
+      <!-- Import the results from a txt file. -->
+      <Document src="assets/101_tom_introduction.txt"/>
+    </output>
+  </example>
+
+  <!-- In this case, the input is inferred as a human message. -->
+  <input><img src="assets/101_jerry_mouse.jpg" alt="The image contains the Jerry mouse character." syntax="multimedia" /></input>
+
+</poml>

data/examples/102_render_xml.poml

@@ -0,0 +1,40 @@
+<poml syntax="xml">
+<role>Senior Systems Architecture Consultant</role>
+<task>Legacy System Migration Analysis</task>
+
+<cp caption="Context">
+  <list>
+    <item>Fortune 500 retail company</item>
+    <item>Current system: 15-year-old monolithic application</item>
+    <item>500+ daily users</item>
+    <item>99.99% uptime requirement</item>
+  </list>
+</cp>
+
+<cp caption="Required Analysis" captionSerialized="RequiredAnalysis">
+  <list listStyle="decimal">
+    <item>Migration risks and mitigation strategies</item>
+    <item>Cloud vs hybrid options</item>
+    <item>Cost-benefit analysis</item>
+    <item>Implementation roadmap</item>
+  </list>
+</cp>
+
+<output-format>
+  <list>
+    <item>Executive brief (250 words)</item>
+    <item>Technical details (500 words)</item>
+    <item>Risk matrix</item>
+    <item>Timeline visualization</item>
+    <item>Budget breakdown</item>
+  </list>
+</output-format>
+
+<cp caption="Constraints">
+  <list>
+    <item>Must maintain operational continuity</item>
+    <item>Compliance with GDPR and CCPA</item>
+    <item>Maximum 18-month implementation window</item>
+    </list>
+  </cp>
+</poml>

data/examples/103_word_todos.poml

@@ -0,0 +1,27 @@
+<poml>
+<Task>I developed a project called Prompt Wizard and I want to write a blog to publish on the company website. I have already written a draft of the blog. There has been figures, numbers in tables, the key challenges, motivations, as well as some titles and subtitles. I want you to complete the <code>[TODO]</code>s in the draft.</Task>
+
+<OutputFormat>Your response should be in the following format:
+
+<Code inline="false">
+<List>
+<ListItem>TODO 1: </ListItem>
+<ListItem>TODO 2: </ListItem>
+<ListItem>...</ListItem>
+</List>
+</Code>
+</OutputFormat>
+
+<input>
+<Document src="assets/103_prompt_wizard.docx" />
+</input>
+
+<stylesheet>
+{
+    "image": {
+        "maxWidth": 500,
+        "maxHeight": 500
+    }
+}
+</stylesheet>
+</poml>

data/examples/104_financial_analysis.poml

@@ -0,0 +1,33 @@
+<poml>
+<SystemMessage>
+
+<task>
+Given the stock ticker, provide a full and up-to-date financial analysis covering the following aspects, cite sources.
+</task>
+
+<list listStyle="decimal">
+<item>Current stock price, recent performance trends, and historical comparison.</item>
+<item>Key financial ratios (e.g., P/E ratio, forward P/E, Price/Free cash flow, EPS growth this year, Return on equity, return on investment, current ratio, net profit margin, debt-to-equity ratio) and what they indicate about the company's financial health.</item>
+<item>Support and resistance prices of the stock and how current indicators may drive the direction of the stock</item>
+<item>Recent earnings reports, revenue growth or decline, and net income trends over the past quarter. Please also include if latest EPS report beat estimates.</item>
+<item>Industry comparison to determine the company's standing relative to its peers.</item>
+<item>Current analyst ratings, target price forecasts, and recent upgrades or downgrades.</item>
+<item>Overall summary on whether the stock is considered a 'buy', 'hold', or 'sell' based on current financial data and market sentiment.</item>
+</list>
+</SystemMessage>
+
+<HumanMessage>
+<table src="assets/104_mag7.xlsx" selectedRecords=":-1" syntax="markdown" />
+
+<p>The following two charts on a visualization of the table above. One of them shows the absolute price of the stocks, and the other one shows the price normalized by the price of the first day.</p>
+
+<img src="assets/104_chart_price.png" syntax="multimedia" />
+
+<img src="assets/104_chart_normalized_price.png" syntax="multimedia" />
+
+<Hint>
+The table contains stock tickers of 7 companies. Please analyze and give financial analysis and comparison for them.
+</Hint>
+</HumanMessage>
+
+</poml>

data/examples/105_write_blog_post.poml

@@ -0,0 +1,48 @@
+<poml>
+<task className="instruction">Create a blog post with these specifications:</task>
+
+<output-format className="instruction">
+<list listStyle="decimal">
+  <item>Title: [SEO-friendly title]</item>
+  <item>Introduction (100 words)
+  <list>
+    <item>Hook statement</item>
+    <item>Context setting</item>
+    <item>Main points preview</item>
+  </list>
+  </item>
+  <item>Main body (800 words)
+  <list>
+    <item>3-4 main points</item>
+    <item>Each point: [subtitle + 200 words]</item>
+    <item>Include real examples</item>
+    <item>Add actionable tips</item>
+  </list>
+  </item>
+  <item>Conclusion (100 words)
+  <list>
+    <item>Summary of key points</item>
+    <item>Call to action</item>
+  </list>
+  </item>
+</list>
+</output-format>
+
+<cp className="instruction" caption="Style" captionSerialized="style">
+<list>
+  <item>Tone: Professional but conversational</item>
+  <item>Level: Intermediate audience</item>
+  <item>Voice: Active, engaging</item>
+  <item>Format: Scannable, with subheadings</item>
+</list>
+</cp>
+
+<cp className="instruction" caption="Include" captionSerialized="include">
+<list>
+  <item>Practical examples</item>
+  <item>Statistics or research</item>
+  <item>Actionable takeaways</item>
+  <item>Relevant analogies</item>
+</list>
+</cp>
+</poml>

data/examples/106_research.poml

@@ -0,0 +1,36 @@
+<poml>
+<task>You are given various potential options or approaches for a project. Convert these into a well-structured research plan.</task>
+
+<stepwise-instructions>
+<list listStyle="decimal">
+<item>Identifies Key Objectives
+  <list listStyle="dash">
+    <item>Clarify what questions each option aims to answer</item>
+    <item>Detail the data/info needed for evaluation</item>
+  </list>
+</item>
+<item>Describes Research Methods
+  <list listStyle="dash">
+    <item>Outline how you’ll gather and analyze data</item>
+    <item>Mention tools or methodologies for each approach</item>
+  </list>
+</item>
+
+<item>Provides Evaluation Criteria
+  <list listStyle="dash">
+    <item>Metrics, benchmarks, or qualitative factors to compare options  </item>
+    <item>Criteria for success or viability</item>
+  </list>
+</item>
+
+<item>Specifies Expected Outcomes
+  <list listStyle="dash">
+    <item>Possible findings or results  </item>
+    <item>Next steps or actions following the research</item>
+  </list>
+</item>
+</list>
+
+Produce a methodical plan focusing on clear, practical steps.
+</stepwise-instructions>
+</poml>

data/examples/107_read_report_pdf.poml

@@ -0,0 +1,4 @@
+<poml>
+<p>Provide a concise executive summary of the following text, highlighting key points, objectives, and outcomes. Keep the summary under 150 words and ensure it is suitable for a professional audience.</p>
+<Document syntax="text" src="assets/107_usenix_paper.pdf" selectedPages="1:3" />
+</poml>

data/examples/201_orders_qa.poml

@@ -0,0 +1,50 @@
+<poml>
+  <role>You are a chatbot agent answering customer's questions in a chat.</role>
+
+  <task>
+    Your task is to answer the customer's question using the data provided in the data section.
+    <!-- Use listStyle property to change the style of a list. -->
+    <list listStyle="decimal">
+      <item>You can access order history in the orders section including email id and order total with payment summary.</item>
+      <item>Refer to orderlines for item level details within each order in orders.</item>
+    </list>
+  </task>
+
+  <!-- cp means CaptionedParagraph, which is a paragraph with customized headings. -->
+  <cp caption="Data">
+    <cp caption="Orders">
+      <!-- Use table to read a csv file. By default, it follows its parents' style (markdown in this case). -->
+      <table src="assets/201_orders.csv" />
+    </cp>
+
+    <cp caption="Orderlines">
+      <!-- Use syntax to specify its output format. -->
+      <table src="assets/201_orderlines.csv" syntax="tsv" />
+    </cp>
+  </cp>
+
+  <!-- This can also be stepwise-instructions, and it's case-insensitive. -->
+  <StepwiseInstructions>
+    <!-- Read a file and save it as instructions -->
+    <let src="assets/201_order_instructions.json" name="instructions"/>
+    <!-- Use a for loop to iterate over the instructions, use {{ }} to evaluate an expression -->
+    <p for="ins in instructions">
+      Instruction {{loop.index+1}}: {{ ins }}
+    </p>
+  </StepwiseInstructions>
+
+  <!-- Specify the speaker of a block. -->
+  <HumanMessage>
+    <!-- Use a question-answer format. -->
+    <qa>How much did I pay for my last order?</qa>
+  </HumanMessage>
+
+  <!-- Use stylesheet (a CSS-like JSON) to modify the style in a batch. -->
+  <stylesheet>
+    {
+      "cp": {
+        "captionTextTransform": "upper"
+      }
+    }
+  </stylesheet>
+</poml>

data/examples/202_arc_agi.poml

@@ -0,0 +1,36 @@
+<poml>
+<SystemMessage>Be brief and clear in your responses</SystemMessage>
+<let src="assets/202_arc_agi_data.json"/>
+<HumanMessage>
+<p>Find the common rule that maps an input grid to an output grid, given the examples below.</p>
+<examples>
+  <example for="example in train" chat="false" caption="Example {{ loop.index }}" captionStyle="header">
+    <input><table records="{{ example.input }}"/></input>
+    <output><table records="{{ example.output }}"/></output>
+  </example>
+</examples>
+
+<p>Below is a test input grid. Predict the corresponding output grid by applying the rule you found. Your final answer should just be the text output grid itself.</p>
+<input><table records="{{ test[0].input }}"/></input>
+</HumanMessage>
+
+<stylesheet>
+{
+  "table": {
+    "syntax": "csv",
+    "writerOptions": {
+        "csvHeader": false,
+        "csvSeparator": " "
+    }
+  },
+  "input": {
+    "captionEnding": "colon-newline",
+    "captionStyle": "plain"
+  },
+  "output": {
+    "captionEnding": "colon-newline",
+    "captionStyle": "plain"
+  }
+}
+</stylesheet>
+</poml>

data/examples/301_generate_poml.poml

@@ -0,0 +1,46 @@
+<poml>
+<let src="105_write_blog_post.poml" name="blog_post" />
+<let src="106_research.poml" name="research" />
+<let src="202_arc_agi.poml" name="arc_agi" />
+<let src="107_read_report_pdf.poml" name="read_report" />
+<p>
+<span whiteSpace="trim">
+// PromptLibrary.jsx
+
+/* Create a blog post. The prompt contains very specific instructions around output format, styles, and what to include in the content. */
+<span whiteSpace="trim">
+function blog_post() {
+  return {{blog_post.replace(/^/gm, '  ').trimStart()}};
+}
+</span>
+
+/* Conduct in-depth research with AI, such as tackling academic papers, business analyses, or large investigative projects. */
+<span whiteSpace="trim">
+function research() {
+  return {{research.replace(/^/gm, '  ').trimStart()}};
+}
+</span>
+
+/* Test the ability of an LLM to perform a complex reasoning task -- ARC-AGI. The data is in `arc_agi_data.json`.
+ */
+<span whiteSpace="trim">
+function arc_agi() {
+  return {{arc_agi.replace(/^/gm, '  ').trimStart()}};
+}
+</span>
+
+/* Summarize a report, such as a research paper or a business report. */
+<span whiteSpace="trim">
+function read_report() {
+  return {{read_report.replace(/^/gm, '  ').trimStart()}};
+}
+</span>
+
+/* Write a entertaining story that is engaging, imaginative and captivating for the audience. */
+<span whiteSpace="trim">
+function storyteller() {
+  return
+</span>
+</span>
+</p>
+</poml>

data/examples/README.md

@@ -0,0 +1,50 @@
+# How to Test the poml Ruby Gem Locally with Example Files
+
+1. **Install dependencies** (from the gem root):
+	```sh
+	bundle install
+	```
+
+2. **Open an IRB (interactive Ruby) session** in the gem root:
+
+```sh
+bundle exec irb -Ilib -rpoml
+```
+
+3. **Run the gem on an example file** (replace the path and context as needed):
+
+```ruby
+result = Poml.process(
+  markup: "examples/101_explain_character.poml",
+  context: { name: "World" },
+  format: "raw"
+)
+puts result
+```
+
+You should see the rendered output with the context variable replaced.
+
+If you want to run from a Ruby script, use the same code as above in a `.rb` file and run it with `bundle exec ruby your_script.rb`.
+# POML Example Library
+
+This directory contains example POML files demonstrating a variety of use cases. Examples are organized by difficulty:
+
+- **Beginner:** Filenames start with `1XX_`
+- **Intermediate:** Filenames start with `2XX_`
+- **Advanced:** Filenames start with `3XX_`
+
+Each example highlights different POML features, such as structured prompting, data handling, and templating.
+
+Non-POML examples (e.g., Python or JavaScript scripts) are prefixed with `4XX_` and use appropriate file extensions. Inline comments explain their usage.
+
+## Contributing
+
+Contributions are welcome! To add or improve an example:
+
+- Follow the naming conventions above.
+- Include clear explanations and comments in your examples.
+- Place any assets in an `assets/` subdirectory within the example's folder.
+- If your example includes expected output, place it in an `expects/` subdirectory.
+
+Submit your changes via pull request.
+

data/examples/_generate_expects.py

@@ -0,0 +1,35 @@
+import os
+import poml
+import io
+import sys
+from contextlib import redirect_stdout
+
+
+def process_example(example_content, output_file):
+    """
+    Process the example content and return the expected output.
+    """
+    # Capture stdout
+    poml.poml(example_content, format="raw", output_file=output_file, extra_args=["--prettyPrint", "true"])
+
+
+def generate_expectations():
+    """
+    Generate the expected output files for the examples.
+    """
+    examples_dir = os.path.abspath(os.path.dirname(__file__))
+    expect_dir = os.path.join(examples_dir, "expects")
+    print("Generating expectations in:", expect_dir)
+
+    for example_file in sorted(os.listdir(examples_dir)):
+        if example_file.endswith(".poml"):
+            print(f"Processing example: {example_file}")
+            # Generate the expected output
+            process_example(
+                os.path.join(examples_dir, example_file),
+                os.path.join(expect_dir, example_file.replace(".poml", ".txt")),
+            )
+
+
+if __name__ == "__main__":
+    generate_expectations()

data/examples/assets/101_tom_introduction.txt

@@ -0,0 +1,9 @@
+Hello there! Let's take a look at this picture together. What do you see? That's right, it's Tom from the famous cartoon series "Tom and Jerry"!
+
+Tom is a gray and white domestic shorthair cat. In this picture, he looks a bit worried or scared, doesn't he? You can tell by his big, wide eyes and the way his mouth is shaped. Maybe Jerry, the clever little mouse, has played another trick on him!
+
+Now, let's talk a little more about Tom and Jerry so you can understand why Tom might look this way. "Tom and Jerry" is a fun cartoon that has been around since 1940. It was created by William Hanna and Joseph Barbera. The show is all about the funny and sometimes crazy adventures of Tom the cat and Jerry the mouse. Tom is always trying to catch Jerry, but Jerry is very smart and always finds a way to escape or trick Tom.
+
+Even though Tom and Jerry are often seen fighting, they do care about each other and sometimes work together to solve problems. The cartoon is full of funny moments, and even though they play tricks on each other, it's all in good fun.
+
+So, whenever you see Tom looking like this, you can imagine that he's probably just been outsmarted by Jerry once again! But don't worry, Tom never gives up and always comes back for more adventures.

data/examples/assets/201_order_instructions.json

@@ -0,0 +1,7 @@
+[
+    "If there is no data that can help answer the question, respond with \"I do not have this information. Please contact customer service\".",
+    "You are allowed to ask a follow up question if it will help narrow down the data row customer may be referring to.",
+    "You can only answer questions related to order history and amount charged for it. Include OrderId in the response, when applicable.",
+    "For everything else, please redirect to the customer service agent.",
+    "Answer in plain English and no sources are required."
+]

data/examples/assets/201_orderlines.csv

@@ -0,0 +1,2 @@
+OrderId,OrderLineId,CreatedTimestamp,ItemDescription,Quantity,FulfillmentStatus,ExpectedDeliveryDate,ActualDeliveryDate,ActualShipDate,ExpectedShipDate,TrackingInformation,ShipToAddress,CarrierCode,DeliveryMethod,UnitPrice,OrderLineSubTotal,LineShippingCharge,TotalTaxes,Payments
+CC10182,1,,Shorts,0.0,unshipped,2024-01-31,2024-02-01,2024-01-30,2024-01-29,,,,ShipToAddress,115.99,0.0,0.0,0.0,

data/examples/assets/201_orders.csv

@@ -0,0 +1,3 @@
+OrderId,CustomerEmail,CreatedTimestamp,IsCancelled,OrderTotal,PaymentSummary
+CC10182,222larabrown@gmail.com,2024-01-19,true,0.0,Not available
+CC10183,baklavainthebalkans@gmail.com,2024-01-19,true,0.0,Not available

data/examples/assets/202_arc_agi_data.json

@@ -0,0 +1 @@
+{"train": [{"input": [[2, 2, 2], [2, 1, 8], [2, 8, 8]], "output": [[2, 2, 2], [2, 5, 5], [2, 5, 5]]}, {"input": [[1, 1, 1], [8, 1, 3], [8, 2, 2]], "output": [[1, 1, 1], [5, 1, 5], [5, 5, 5]]}, {"input": [[2, 2, 2], [8, 8, 2], [2, 2, 2]], "output": [[2, 2, 2], [5, 5, 2], [2, 2, 2]]}, {"input": [[3, 3, 8], [4, 4, 4], [8, 1, 1]], "output": [[5, 5, 5], [4, 4, 4], [5, 5, 5]]}], "test": [{"input": [[1, 3, 2], [3, 3, 2], [1, 3, 2]], "output": [[5, 3, 5], [3, 3, 5], [5, 3, 5]]}]}