POML Ruby Gem - Tutorial

Welcome to the comprehensive tutorial for the POML (Prompt Oriented Markup Language) Ruby gem. This tutorial will guide you through all features and capabilities of POML for creating structured AI prompts.

What is POML?

POML is a markup language designed for creating structured, reusable AI prompts. It provides components for organizing content, managing templates, handling data, and integrating with various AI services.

Key Concepts for Ruby Implementation

Output Formats and Rendering

The Ruby POML gem uses a format-aware rendering system:

• Default rendering: Produces Markdown-like output optimized for readability
• HTML components: Use <output format="html">content</output> for HTML output (<h1>, <b>, <i> tags)
• JSON/XML formats: Use <output format="json">content</output> or <output format="xml">content</output> for structured data
• Text format: Use <output format="text">content</output> for plain text output

Example - Getting HTML Output:

markup = <<~POML
  <poml>
    <role>Documentation Writer</role>
    <output format="html">
      <h1>Main Title</h1>
      <p>Content with <b>bold</b> and <i>italic</i> text.</p>
    </output>
  </poml>
POML

result = Poml.process(markup: markup)
puts result['output']  # Contains HTML: <h1>Main Title</h1><p>Content with <b>bold</b>...

Component Behavior

• Headers: <h1>Title</h1> produces # Title by default, <h1>Title</h1> with HTML format
• Formatting: <b>bold</b> produces **bold** by default, <b>bold</b> with HTML format
• Structure: Most components adapt their output based on the specified format

Quick Start

require 'poml'

# Simple example
markup = <<~POML
  <poml>
    <role>Code Reviewer</role>
    <task>Review the following Ruby code for best practices</task>
    <hint>Focus on performance and readability</hint>
  </poml>
POML

result = Poml.process(markup: markup)
puts result['content']

Tutorial Structure

Core Concepts

• Basic Usage - Fundamental POML concepts and syntax
• Output Formats - All supported output formats with examples
• Template Engine - Variables, conditionals, and loops

Components Reference

• Components Overview - All available POML components
• Chat Components - AI, human, and system message components
• Formatting Components - Text formatting and structure
• Data Components - Tables, objects, and file handling
• Media Components - Images and multimedia
• Schema Components - Output schemas and tool definitions
• Utility Components - Conversations, trees, and folders

Advanced Features

• Tool Registration - Enhanced tool registration system
• Inline Rendering - Seamless text flow with inline components
• Error Handling - Robust error handling patterns
• Performance - Caching and optimization strategies

Integration Guides

• Rails Integration - Using POML in Rails applications
• Sinatra Integration - Building APIs with POML
• Background Jobs - Async processing patterns

Complete Examples

• Code Review System - Complete code review workflow
• API Documentation - Automated documentation generation
• Content Generation - Dynamic content creation

Key Features

• 🎯 Multiple Output Formats: Raw text, OpenAI Chat, LangChain, Pydantic, and more
• 📝 Template Engine: Variables, conditionals, loops, and meta variables

XML Mode and Component Rendering

Dual Rendering Architecture

The Ruby POML implementation supports dual rendering modes that automatically adapt based on context:

Standard Mode (Default)

Components render to Markdown-like syntax for readability:

• <code>example</code> → `example`
• <b>bold</b> → **bold**
• <i>italic</i> → *italic*

XML Mode (with syntax="xml")

Components preserve XML structure with attributes:

• <code inline="true">example</code> → <code inline="true">example</code>
• <b>bold text</b> → <b>bold text</b>
• <list style="decimal">... → <list style="decimal">...

Important XML Parsing Details

Component Disambiguation: The parser uses precise boundary detection to distinguish between similar component names:

• <code> tags are handled separately from <code-block> tags
• Regex patterns use negative lookahead ((?!-)) to prevent false matches
• This ensures proper XML parsing when multiple component types are present

Attribute Preservation: When syntax="xml" is specified, component attributes are maintained in the output, enabling rich structured content while preserving XML compatibility.

Example: Context-Aware Rendering

# Standard mode
markup1 = '<poml><code>example</code></poml>'
result1 = Poml.process(markup: markup1)
# Output: `example`

# XML mode
markup2 = '<poml syntax="xml"><code inline="true">example</code></poml>'
result2 = Poml.process(markup: markup2)  
# Output: <code inline="true">example</code>

Getting Started

• 🔧 Tool Registration: Enhanced tool definition with parameter conversion
• 📊 Data Components: Tables, objects, files, and structured data
• 🖼️ Media Support: Images with URL fetching and base64 encoding
• 💬 Chat Components: Specialized AI conversation components
• 🎨 Inline Rendering: Seamless text flow with component integration
• ⚡ Performance: Caching, optimization, and error handling

Installation

Add to your Gemfile:

gem 'poml'

Or install directly:

gem install poml

Version Compatibility

• Ruby: >= 2.7.0
• Current Version: 0.0.7
• Test Coverage: 399 tests, 2812 assertions, 100% pass rate (0 failures, 0 errors, 0 skips)

Next Steps

1. Start with Basic Usage to learn core concepts
2. Explore Components for detailed component reference
3. Check Integration Guides for your specific use case
4. Review Examples for real-world implementations

Happy prompting! 🚀