poml 0.0.5 → 0.0.7

data/docs/tutorial/components/index.md

@@ -0,0 +1,366 @@
+# Components Overview
+
+POML provides a rich set of components for creating structured, dynamic AI prompts. This page provides an overview of all available components organized by category.
+
+## Component Categories
+
+### [Chat Components](chat-components.md)
+
+Specialized components for creating structured AI conversations:
+
+- **`<system>`** - System-level instructions and context
+- **`<human>`** - User messages and queries  
+- **`<ai>`** - Assistant responses and few-shot examples
+
+```ruby
+<poml>
+  <system>You are a helpful programming assistant.</system>
+  <human>How do I optimize this Ruby code?</human>
+  <ai>Here are some optimization strategies...</ai>
+</poml>
+```
+
+### [Formatting Components](formatting.md)
+
+Text formatting and structure components:
+
+- **`<b>`** - **Bold text**
+- **`<i>`** - *Italic text*
+- **`<u>`** - Underlined text  
+- **`<s>`** - ~~Strikethrough text~~
+- **`<code>`** - `Inline code`
+- **`<h1>` to `<h6>`** - Headers
+- **`<br>`** - Line breaks
+- **`<p>`** - Paragraphs
+
+### [Data Components](data-components.md)
+
+Components for handling data and structured content:
+
+- **`<table>`** - Render tables from CSV/JSON data
+- **`<object>`** - Object serialization (JSON, YAML, XML)
+- **`<file>`** - File content reading with path resolution
+- **`<folder>`** - Directory listing with depth control
+
+### [Media Components](media-components.md)
+
+Multimedia content components:
+
+- **`<img>`** - Image processing with URL fetching and base64 support
+- **`<audio>`** - Audio file handling
+
+### [Schema Components](schema-components.md)
+
+Components for defining structured AI responses and tools:
+
+- **`<output-schema>`** - AI response schema definitions
+- **`<tool-definition>`** - AI tool registration with parameters
+- **`<meta type="output-schema">`** - Legacy schema support
+- **`<meta type="tool-definition">`** - Legacy tool definition support
+
+### [Utility Components](utility-components.md)
+
+Helper components for specialized content:
+
+- **`<list>` & `<item>`** - Unordered lists with nested content
+- **`<conversation>`** - Chat conversation display
+- **`<tree>`** - Tree structure display with JSON data
+- **`<include>`** - Template inclusion and composition
+
+### Template Engine Components
+
+Dynamic content generation components:
+
+- **`<if condition="">`** - Conditional logic with comparisons
+- **`<for variable="" items="">`** - Loops and iteration
+- **`{{variable}}`** - Variable substitution
+- **`<meta variables="">`** - Template variables definition
+
+### Structural Components
+
+Basic structural components:
+
+- **`<poml>`** - Root container for all POML content
+- **`<role>`** - Define AI role and expertise
+- **`<task>`** - Specify what AI should accomplish
+- **`<hint>`** - Provide additional guidance
+
+## Common Attributes
+
+### Global Attributes
+
+Most components support these attributes:
+
+- **`inline="true"`** - Enable inline rendering for seamless text flow
+- **Template variables** - Use `{{variable}}` in any attribute value
+
+### Chat-Specific Attributes
+
+Chat components support:
+
+- **`role="..."`** - Override default role (system, user, assistant)
+- **`speaker="..."`** - Custom speaker name for conversations
+
+### Formatting Attributes
+
+Components support various formatting attributes:
+
+- **`style="..."`** - Custom styling
+- **`class="..."`** - CSS class names
+
+## Component Usage Patterns
+
+### Basic Structure
+
+```ruby
+<poml>
+  <role>Expert in {{domain}}</role>
+  <task>{{primary_objective}}</task>
+  
+  <p>Context and instructions...</p>
+  
+  <list>
+    <item>First requirement</item>
+    <item>Second requirement</item>
+  </list>
+  
+  <hint>Additional guidance</hint>
+</poml>
+```
+
+### Chat Conversation
+
+```ruby
+<poml>
+  <system>You are a {{expertise}} expert.</system>
+  
+  <human>
+    I need help with {{problem_description}}.
+    
+    <p>Specific requirements:</p>
+    <list>
+      <for variable="req" items="{{requirements}}">
+        <item>{{req}}</item>
+      </for>
+    </list>
+  </human>
+</poml>
+```
+
+### Data Analysis
+
+```ruby
+<poml>
+  <role>Data Analyst</role>
+  <task>Analyze the provided dataset</task>
+  
+  <table src="{{data_file}}" maxRecords="10" />
+  
+  <output-schema name="AnalysisResult">
+  {
+    "type": "object",
+    "properties": {
+      "insights": {"type": "array"},
+      "recommendations": {"type": "array"}
+    }
+  }
+  </output-schema>
+</poml>
+```
+
+### Code Review
+
+```ruby
+<poml>
+  <role>Senior {{language}} Developer</role>
+  <task>Review code for best practices</task>
+  
+  <file src="{{code_file}}" />
+  
+  <p>Review focus areas:</p>
+  <list>
+    <item><b>Performance</b> - Algorithm efficiency</item>
+    <item><b>Security</b> - Vulnerability assessment</item>
+    <item><b>Maintainability</b> - Code organization</item>
+  </list>
+  
+  <tool-definition name="suggest_improvements">
+  {
+    "description": "Suggest specific code improvements",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "file_path": {"type": "string"},
+        "line_number": {"type": "integer"},
+        "suggestion": {"type": "string"},
+        "priority": {"type": "string", "enum": ["low", "medium", "high"]}
+      }
+    }
+  }
+  </tool-definition>
+</poml>
+```
+
+## Component Combinations
+
+### Inline Formatting
+
+```ruby
+<p>
+  The <code inline="true">{{method_name}}</code> method should return a 
+  <b inline="true">{{return_type}}</b> value, not 
+  <s inline="true">{{incorrect_type}}</s>.
+</p>
+```
+
+### Conditional Content
+
+```ruby
+<if condition="{{include_examples}}">
+  <p><b>Examples:</b></p>
+  <for variable="example" items="{{examples}}">
+    <p><i>Example {{example.index}}:</i></p>
+    <code>{{example.code}}</code>
+  </for>
+</if>
+```
+
+### Nested Structures
+
+```ruby
+<list>
+  <for variable="category" items="{{categories}}">
+    <item>
+      <b>{{category.name}}</b>
+      <list>
+        <for variable="item" items="{{category.items}}">
+          <item>{{item.name}} - {{item.description}}</item>
+        </for>
+      </list>
+    </item>
+  </for>
+</list>
+```
+
+## Advanced Features
+
+### Template Composition
+
+```ruby
+<!-- Base template -->
+<poml>
+  <role>{{role_type}} Expert</role>
+  <task>{{main_task}}</task>
+  
+  <include src="{{template_path}}" />
+  
+  <if condition="{{include_footer}}">
+    <include src="templates/footer.poml" />
+  </if>
+</poml>
+```
+
+### Multi-Format Support
+
+```ruby
+<!-- Works across all output formats -->
+<poml>
+  <system>You are a helpful assistant.</system>
+  
+  <output-schema name="Response">
+  {
+    "type": "object",
+    "properties": {
+      "answer": {"type": "string"},
+      "confidence": {"type": "number"}
+    }
+  }
+  </output-schema>
+  
+  <human>{{user_question}}</human>
+</poml>
+```
+
+### Error Handling
+
+```ruby
+<poml>
+  <role>Support Assistant</role>
+  <task>Help resolve the issue</task>
+  
+  <if condition="{{error_logs}}">
+    <p><b>Error Analysis:</b></p>
+    <file src="{{error_logs}}" />
+  </if>
+  
+  <if condition="!{{error_logs}}">
+    <p>⚠️ No error logs provided. Please share relevant error information.</p>
+  </if>
+</poml>
+```
+
+## Performance Considerations
+
+### Component Efficiency
+
+- **Light components**: `<p>`, `<b>`, `<i>`, `<code>` - Very fast
+- **Medium components**: `<list>`, `<table>`, `<if>`, `<for>` - Moderate processing
+- **Heavy components**: `<file>`, `<img>`, `<include>` - I/O dependent
+
+### Optimization Tips
+
+1. **Use inline rendering** for seamless text flow
+2. **Limit file operations** with `maxRecords` on tables
+3. **Cache include templates** for repeated use
+4. **Validate schemas** before processing for better error handling
+
+### Memory Usage
+
+```ruby
+# Good: Process in chunks for large datasets
+<table src="large_dataset.csv" maxRecords="100" />
+
+# Good: Use conditions to avoid unnecessary processing
+<if condition="{{debug_mode}}">
+  <file src="debug.log" />
+</if>
+
+# Good: Limit nested loops
+<for variable="category" items="{{categories}}">
+  <if condition="{{category.items.length}} <= 10">
+    <for variable="item" items="{{category.items}}">
+      <item>{{item.name}}</item>
+    </for>
+  </if>
+</for>
+```
+
+## Component Reference Quick Links
+
+### By Use Case
+
+- **Chat Applications**: [Chat Components](chat-components.md)
+- **Data Processing**: [Data Components](data-components.md)
+- **Content Generation**: [Formatting Components](formatting.md)
+- **AI Integration**: [Schema Components](schema-components.md)
+- **Dynamic Content**: [Template Engine](../template-engine.md)
+
+### By Complexity
+
+- **Beginner**: `<p>`, `<b>`, `<i>`, `<list>`, `<item>`
+- **Intermediate**: `<if>`, `<for>`, `<table>`, `<img>`, `<system>`, `<human>`
+- **Advanced**: `<output-schema>`, `<tool-definition>`, `<include>`, `<meta>`
+
+### By Output Format
+
+- **All Formats**: Basic formatting, structure, template engine
+- **Chat Formats**: `<system>`, `<human>`, `<ai>` components
+- **Schema Formats**: `<output-schema>`, `<tool-definition>` components
+
+## Next Steps
+
+1. **Start Simple** - Begin with [Formatting Components](formatting.md)
+2. **Add Structure** - Learn [Template Engine](../template-engine.md)  
+3. **Enable Chat** - Explore [Chat Components](chat-components.md)
+4. **Add Intelligence** - Master [Schema Components](schema-components.md)
+5. **Optimize** - Review [Performance Guide](../advanced/performance.md)

data/docs/tutorial/components/media-components.md

@@ -0,0 +1,259 @@
+# Media Components
+
+This guide covers POML components for handling multimedia content including images and other media types.
+
+## Image Component
+
+The `<img>` component displays images in your POML documents with advanced processing capabilities.
+
+### Basic Usage
+
+```ruby
+require 'poml'
+
+# Local image file
+markup = <<~POML
+  <poml>
+    <role>Image Analyst</role>
+    <task>Describe the contents of this image</task>
+    <img src="photo.jpg" alt="User photo" />
+  </poml>
+POML
+
+result = Poml.process(markup: markup)
+puts result['content']
+```
+
+### URL-based Images
+
+The Ruby implementation supports fetching images from HTTP(S) URLs:
+
+```ruby
+markup = <<~POML
+  <poml>
+    <role>Visual Analyst</role>
+    <img src="https://example.com/image.png" alt="Remote image" />
+  </poml>
+POML
+
+result = Poml.process(markup: markup)
+```
+
+### Advanced Image Processing
+
+The Ruby implementation uses **libvips** for high-performance image processing:
+
+#### Image Resizing
+
+```ruby
+# Fit within bounds (preserves aspect ratio)
+markup = <<~POML
+  <poml>
+    <img src="large-photo.jpg" 
+         max-width="800" 
+         max-height="600" 
+         resize="fit" />
+  </poml>
+POML
+
+# Fill area (may crop)
+markup = <<~POML
+  <poml>
+    <img src="photo.jpg" 
+         max-width="400" 
+         max-height="400" 
+         resize="fill" />
+  </poml>
+POML
+
+# Stretch to exact dimensions
+markup = <<~POML
+  <poml>
+    <img src="photo.jpg" 
+         max-width="300" 
+         max-height="200" 
+         resize="stretch" />
+  </poml>
+POML
+```
+
+#### Format Conversion
+
+```ruby
+# Convert JPEG to PNG
+markup = <<~POML
+  <poml>
+    <img src="photo.jpg" type="png" />
+  </poml>
+POML
+
+# Convert to WebP for better compression
+markup = <<~POML
+  <poml>
+    <img src="large-image.png" type="webp" />
+  </poml>
+POML
+```
+
+### Component Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `src` | String | Path to image file or HTTP(S) URL |
+| `alt` | String | Alternative text for accessibility |
+| `base64` | String | Base64 encoded image data (cannot use with `src`) |
+| `type` | String | Output format: `jpeg`, `png`, `webp`, `tiff`, `gif` |
+| `max-width` | Integer | Maximum width in pixels |
+| `max-height` | Integer | Maximum height in pixels |
+| `resize` | String | Resize mode: `fit`, `fill`, `stretch` |
+| `position` | String | Position: `top`, `bottom`, `here` (default: `here`) |
+| `syntax` | String | Output syntax: `multimedia`, `markdown`, etc. |
+
+### Resize Modes
+
+- **`fit`**: Resize to fit within bounds while preserving aspect ratio
+- **`fill`**: Fill the entire area, potentially cropping to maintain aspect ratio
+- **`stretch`**: Stretch to exact dimensions (may distort aspect ratio)
+
+### Format Support
+
+The libvips-powered implementation supports:
+
+- **Input formats**: JPEG, PNG, GIF, WebP, TIFF, BMP, SVG
+- **Output formats**: JPEG (with quality control), PNG, WebP, TIFF, GIF
+- **Automatic format detection** from file headers
+- **MIME type handling** for web images
+
+### Base64 Encoding
+
+All processed images are automatically converted to base64 data URLs:
+
+```ruby
+markup = <<~POML
+  <poml>
+    <img src="photo.jpg" />
+  </poml>
+POML
+
+result = Poml.process(markup: markup)
+# Result contains: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...
+```
+
+### Error Handling
+
+The implementation provides graceful error handling:
+
+```ruby
+# Missing file
+markup = '<poml><img src="missing.jpg" alt="Missing image" /></poml>'
+result = Poml.process(markup: markup)
+# Returns alt text: "Missing image"
+
+# Invalid URL
+markup = '<poml><img src="https://invalid-url.com/image.jpg" /></poml>'
+result = Poml.process(markup: markup)
+# Returns error message with graceful fallback
+```
+
+### Fallback Behavior
+
+When libvips is not available, the implementation:
+
+1. **Falls back** to basic image handling
+2. **Warns the user** about limited functionality
+3. **Continues processing** without breaking
+4. **Returns original image data** when possible
+
+### Installation Requirements
+
+For full image processing capabilities:
+
+```bash
+# Install libvips system library (macOS)
+brew install vips
+
+# Install libvips system library (Ubuntu/Debian)
+sudo apt-get install libvips-dev
+
+# Ruby gem is automatically installed with POML
+gem install poml
+```
+
+The ruby-vips gem is automatically included as a dependency.
+
+### Examples
+
+#### Simple Image Display
+
+```ruby
+markup = <<~POML
+  <poml>
+    <role>Photo Critic</role>
+    <task>Analyze the composition of this photograph</task>
+    <img src="artwork.jpg" alt="Artistic photograph" />
+    <instruction>Focus on lighting, composition, and visual impact</instruction>
+  </poml>
+POML
+```
+
+#### Image Processing Pipeline
+
+```ruby
+markup = <<~POML
+  <poml>
+    <role>Image Processor</role>
+    <task>Process and optimize images for web display</task>
+    
+    <h2>Original Image</h2>
+    <img src="large-photo.jpg" alt="Original high-resolution photo" />
+    
+    <h2>Optimized for Web</h2>
+    <img src="large-photo.jpg" 
+         type="webp" 
+         max-width="800" 
+         resize="fit" 
+         alt="Web-optimized version" />
+  </poml>
+POML
+```
+
+#### Multiple Format Output
+
+```ruby
+markup = <<~POML
+  <poml>
+    <role>Format Converter</role>
+    
+    <h3>JPEG Version</h3>
+    <img src="source.png" type="jpeg" />
+    
+    <h3>WebP Version</h3>
+    <img src="source.png" type="webp" />
+    
+    <h3>Thumbnail</h3>
+    <img src="source.png" max-width="150" max-height="150" resize="fill" />
+  </poml>
+POML
+```
+
+## Best Practices
+
+1. **Always provide alt text** for accessibility
+2. **Use appropriate formats**: WebP for web, PNG for transparency, JPEG for photos
+3. **Optimize dimensions** before processing when possible
+4. **Handle errors gracefully** with meaningful alt text
+5. **Consider performance** when processing many large images
+
+## Performance Notes
+
+- **libvips is highly optimized** for image processing
+- **Streaming processing** minimizes memory usage
+- **Format conversion** is efficient with quality control
+- **URL fetching** includes timeout and error handling
+- **Base64 encoding** is automatic and optimized
+
+## See Also
+
+- [Data Components](data-components.md) - For handling other data types
+- [Template Engine](../template-engine.md) - For dynamic image paths
+- [Error Handling](../advanced/error-handling.md) - For robust error handling patterns