roast-ai 0.4.7 → 0.4.8

data/examples/conditional/README.md

@@ -1,161 +0,0 @@
-# Conditional Execution in Roast Workflows
-
-This example demonstrates how to use conditional execution (`if` and `unless`) in Roast workflows.
-
-## Overview
-
-Conditional execution allows workflows to execute different steps based on runtime conditions. This feature supports:
-
-- `if` conditions - execute steps when a condition is true
-- `unless` conditions - execute steps when a condition is false  
-- `then` branches - steps to execute when the condition matches
-- `else` branches - steps to execute when the condition doesn't match (optional, only for `if`)
-
-## Syntax
-
-### If Statement
-
-```yaml
-- if: "{{expression}}"
-  then:
-    - step1
-    - step2
-  else:
-    - step3
-    - step4
-```
-
-### Unless Statement
-
-```yaml
-- unless: "{{expression}}"
-  then:
-    - step1
-    - step2
-```
-
-## Condition Types
-
-Conditions can be:
-
-1. **Ruby Expressions** - Wrapped in `{{...}}`
-   ```yaml
-   - if: "{{output.previous_step.success == true}}"
-   ```
-
-2. **Bash Commands** - Wrapped in `$(...)`
-   ```yaml
-   - if: "$(test -f /path/to/file && echo true || echo false)"
-   ```
-
-3. **Step References** - Reference to previous step output
-   ```yaml
-   - if: "check_condition"  # References a previous step
-   ```
-
-4. **File Checks**
-   ```yaml
-   - if: "{{File.exist?('/tmp/myfile.txt')}}"
-   ```
-
-## Examples
-
-### Basic Example
-
-```yaml
-name: Conditional Example
-tools:
-  - Roast::Tools::Cmd
-
-steps:
-  - check_status: "echo 'success'"
-  
-  - if: "{{output.check_status.strip == 'success'}}"
-    then:
-      - success_action: "echo 'Operation succeeded!'"
-    else:
-      - failure_action: "echo 'Operation failed!'"
-```
-
-### Unless Example
-
-```yaml
-name: Unless Example
-tools: []
-
-steps:
-  - check_file: "test -f /tmp/important.txt && echo exists || echo missing"
-  
-  - unless: "{{output.check_file.strip == 'exists'}}"
-    then:
-      - create_file: "touch /tmp/important.txt"
-      - notify: "echo 'Created missing file'"
-```
-
-### Nested Conditionals
-
-```yaml
-name: Nested Conditionals
-tools: []
-
-steps:
-  - outer_check: "echo 'true'"
-  - inner_check: "echo 'false'"
-  
-  - if: "{{output.outer_check.strip == 'true'}}"
-    then:
-      - if: "{{output.inner_check.strip == 'true'}}"
-        then:
-          - both_true: "echo 'Both conditions are true'"
-        else:
-          - only_outer: "echo 'Only outer condition is true'"
-    else:
-      - outer_false: "echo 'Outer condition is false'"
-```
-
-### Platform-Specific Actions
-
-```yaml
-name: Platform Detection
-tools:
-  - Roast::Tools::Cmd
-
-steps:
-  - detect_os: "uname -s"
-  
-  - if: "{{output.detect_os.strip == 'Darwin'}}"
-    then:
-      - mac_setup: "brew --version || echo 'Homebrew not installed'"
-    else:
-      - if: "{{output.detect_os.strip == 'Linux'}}"
-        then:
-          - linux_setup: "apt-get --version || yum --version"
-        else:
-          - unknown_os: "echo 'Unknown operating system'"
-```
-
-## Best Practices
-
-1. **Use Clear Conditions**: Make your conditions explicit and easy to understand
-2. **Handle Edge Cases**: Always consider what happens when conditions fail
-3. **Test Both Branches**: Ensure both `then` and `else` branches work correctly
-4. **Avoid Deep Nesting**: Keep conditional logic simple and readable
-5. **Use Unless Sparingly**: `unless` can be less intuitive than `if` with negation
-
-## Debugging
-
-To debug conditional execution:
-
-1. Check the workflow output to see which branch was executed
-2. Look for keys like `if_condition_name` or `unless_condition_name` in the output
-3. These keys contain information about the condition evaluation and branch taken
-
-## Running the Example
-
-```bash
-# Run the simple conditional example
-roast execute examples/conditional/simple_workflow.yml
-
-# Run the full conditional example (requires API configuration)
-roast execute examples/conditional/workflow.yml
-```

data/examples/conditional/check_condition/prompt.md

@@ -1 +0,0 @@
-Check if the OS is macOS or Linux and return true if it's macOS, false otherwise.

data/examples/conditional/simple_workflow.yml

@@ -1,15 +0,0 @@
-name: Simple Conditional Test
-tools: []
-
-steps:
-  - set_value: "$(echo 'true')"
-  
-  - if: "{{output.set_value.strip == 'true'}}"
-    then:
-      - success: "$(echo 'If condition worked!')"
-    else:
-      - failure: "$(echo 'If condition failed!')"
-  
-  - unless: "{{output.set_value.strip == 'false'}}"
-    then:
-      - unless_success: "$(echo 'Unless condition worked!')"

data/examples/conditional/workflow.yml

@@ -1,23 +0,0 @@
-name: Conditional Execution Example
-tools:
-  - Roast::Tools::Cmd
-
-steps:
-  - check_os: "$(uname -s)"
-  
-  - if: "{{output.check_os.strip == 'Darwin'}}"
-    then:
-      - mac_message: "$(echo 'Running on macOS!')"
-      - mac_info: "$(sw_vers)"
-    else:
-      - linux_message: "$(echo 'Running on Linux!')"
-      - linux_info: "$(lsb_release -a)"
-  
-  - check_file: "$(test -f /tmp/roast_test.txt && echo exists || echo missing)"
-  
-  - unless: "{{output.check_file.strip == 'exists'}}"
-    then:
-      - create_file: "$(touch /tmp/roast_test.txt && echo 'File created')"
-  
-  - verify_file: "$(ls -la /tmp/roast_test.txt)"
-  - cleanup: "$(rm -f /tmp/roast_test.txt)"

data/examples/context_management_demo/README.md

@@ -1,43 +0,0 @@
-# Context Management Demo
-
-This example demonstrates Roast's automatic context management feature, which helps prevent workflow failures when conversation history exceeds the LLM's context window.
-
-## Features Demonstrated
-
-1. **Automatic Token Tracking**: Monitors token usage throughout workflow execution
-2. **Configurable Thresholds**: Set when to trigger warnings or compaction
-3. **Context Preservation**: Specify critical steps to retain during compaction
-
-## Configuration
-
-```yaml
-context_management:
-  enabled: true          # Enable context management
-  strategy: auto         # Compaction strategy (auto, summarize, prune, none)
-  threshold: 0.8         # Trigger at 80% of context window
-  max_tokens: 10000      # Override default limit (for demo purposes)
-  retain_steps:          # Steps to always keep in full
-    - analyze_requirements
-    - generate_summary
-```
-
-## Running the Demo
-
-```bash
-roast execute context_management_demo
-```
-
-The workflow intentionally generates verbose responses to demonstrate how context management handles large amounts of text without failing.
-
-## What to Observe
-
-1. **Token Usage Warnings**: Watch for warnings as the context approaches limits
-2. **Automatic Handling**: The workflow continues even with large outputs
-3. **Preserved Context**: Critical steps remain accessible throughout execution
-
-## Customization
-
-Try modifying the configuration:
-- Lower `max_tokens` to trigger compaction sooner
-- Change `strategy` to test different compaction approaches
-- Add more steps to `retain_steps` to preserve additional context

data/examples/context_management_demo/workflow.yml

@@ -1,42 +0,0 @@
-name: Context Management Demo
-tools:
-  - Roast::Tools::ReadFile
-  - Roast::Tools::WriteFile
-
-# Context management configuration
-context_management:
-  enabled: true
-  strategy: auto
-  threshold: 0.8  # Trigger compaction at 80% of context window
-  max_tokens: 10000  # Demo with smaller limit for testing
-  retain_steps:
-    - analyze_requirements
-    - generate_summary
-
-steps:
-  - analyze_requirements: |
-      Analyze this text and list the key requirements:
-      
-      We need a system that can:
-      1. Process customer orders
-      2. Track inventory levels
-      3. Generate reports
-      4. Handle refunds
-      5. Integrate with payment systems
-      
-  - expand_details: |
-      For each requirement from the previous step, provide detailed implementation notes,
-      technical considerations, and potential challenges. Be very thorough and verbose
-      to help test the context management system.
-      
-  - generate_more_context: |
-      Now describe the database schema needed for this system. Include all tables,
-      relationships, indexes, and data types. Be extremely detailed.
-      
-  - add_api_design: |
-      Design a complete REST API for this system. Include all endpoints, request/response
-      formats, authentication, and error handling. Provide examples for each endpoint.
-      
-  - generate_summary: |
-      Create a concise executive summary of the system design. Focus on the key decisions
-      and trade-offs made during the design process.

data/examples/direct_coerce_syntax/README.md

@@ -1,32 +0,0 @@
-# Direct Coerce Syntax
-
-This example demonstrates the simplified syntax for specifying `coerce_to` and other configuration options directly on iteration steps.
-
-## Direct Syntax
-
-Configuration options are specified directly on the step:
-
-```yaml
-- repeat:
-    until: "condition"
-    coerce_to: boolean
-    print_response: true
-    model: "claude-3-haiku"
-    steps: [...]
-```
-
-## Benefits
-
-1. **Cleaner YAML** - No unnecessary nesting
-2. **More intuitive** - Configuration options are at the same level as other step properties
-3. **Consistent** - Matches how other step properties are specified
-
-## Supported Options
-
-All step configuration options can be specified directly:
-- `coerce_to` - Type coercion (boolean, llm_boolean, iterable)
-- `print_response` - Whether to print LLM responses
-- `loop` - Auto-loop behavior
-- `json` - JSON response mode
-- `params` - Additional parameters
-- `model` - Model override

data/examples/direct_coerce_syntax/workflow.yml

@@ -1,36 +0,0 @@
-name: Direct Coerce Syntax Demo
-description: Demonstrates the simplified coerce_to syntax without config blocks
-
-steps:
-  # Example 1: Direct coerce_to on repeat
-  - repeat:
-      until: "check_api_ready"
-      coerce_to: boolean  # Direct syntax - no config block needed
-      max_iterations: 5
-      steps:
-        - check_api_ready:
-            prompt: "Check if the API endpoint returns a 200 status"
-        - wait: 2
-  
-  # Example 2: Direct coerce_to on each  
-  - get_data_sources:
-      prompt: "List available data sources, one per line"
-  
-  - each: "get_data_sources"
-    as: "source"
-    coerce_to: iterable  # Direct syntax
-    steps:
-      - validate_source: "Validating {{source}}..."
-      - process_source:
-          prompt: "Process data from {{source}}"
-  
-  # Example 3: Multiple configuration options
-  - repeat:
-      until: "all_tests_pass"
-      coerce_to: llm_boolean  # Override default
-      print_response: true     # Other options work too
-      max_iterations: 10
-      steps:
-        - run_tests: "$(rake test)"
-        - all_tests_pass:
-            prompt: "Did all tests pass successfully?"

data/examples/dot_notation/README.md

@@ -1,37 +0,0 @@
-# Dot Notation Access Example
-
-This example demonstrates the new dot notation access feature for workflow outputs.
-
-## Usage
-
-With the new dot notation feature, you can access output values using Ruby's method syntax instead of hash syntax:
-
-### Before (hash syntax):
-```yaml
-until: "output[:update_fix_count][:fixes_applied] >= 5 || output[:select_next_issue][:no_issues_left] == true"
-```
-
-### After (dot notation):
-```yaml
-until: "output.update_fix_count.fixes_applied >= 5 || output.select_next_issue.no_issues_left?"
-```
-
-### Even cleaner (omitting output prefix):
-```yaml
-until: "update_fix_count.fixes_applied >= 5 || select_next_issue.no_issues_left?"
-```
-
-## Features
-
-1. **Nested access**: `output.step_name.nested.value`
-2. **Boolean predicates**: `output.step_name.is_complete?` returns false for nil/false values
-3. **Direct access**: Omit the `output.` prefix for cleaner syntax
-4. **Backward compatible**: Hash syntax still works (`output[:step_name][:value]`)
-
-## Example Workflow
-
-See `workflow.yml` for a complete example that demonstrates:
-- Setting values in output
-- Using dot notation in conditions
-- Boolean predicate methods
-- Nested value access

data/examples/dot_notation/workflow.yml

@@ -1,44 +0,0 @@
-name: dot_notation_example
-description: Example demonstrating dot notation access for workflow outputs
-
-steps:
-  initialize:
-    prompt: |
-      Initialize the workflow with some sample data.
-      
-      Set output.counter to 0
-      Set output.config.max_iterations to 5
-      Set output.config.enabled to true
-
-  process_items:
-    repeat:
-      # Using dot notation in conditions
-      until: "counter >= config.max_iterations || !config.enabled?"
-      steps:
-        - increment_counter
-        - check_status
-
-  increment_counter:
-    prompt: |
-      Increment the counter by 1.
-      Current counter value: {{counter}}
-      
-      Set output.counter to {{counter}} + 1
-
-  check_status:
-    prompt: |
-      Check if we should continue processing.
-      
-      Current counter: {{counter}}
-      Max iterations: {{config.max_iterations}}
-      
-      If counter is 3, set output.config.enabled to false
-      Set output.status.last_checked to current counter value
-
-  summarize:
-    prompt: |
-      Summarize the results:
-      - Total iterations: {{counter}}
-      - Last checked at: {{status.last_checked}}
-      - Was enabled: {{config.enabled}}
-      - Hit max iterations: {{counter >= config.max_iterations ? "Yes" : "No"}}

data/examples/exit_on_error/README.md

@@ -1,50 +0,0 @@
-# Exit on Error Example
-
-This example demonstrates how to use the `exit_on_error` configuration option to continue workflow execution even when a command fails.
-
-## Use Case
-
-When running a linter like RuboCop on a file with syntax errors or style violations, the command will exit with a non-zero status. By default, this would halt the workflow. However, we often want to:
-
-1. Capture the linter output (including errors)
-2. Analyze what went wrong
-3. Apply fixes based on the analysis
-
-## Configuration
-
-The key configuration is in the step configuration section:
-
-```yaml
-lint_check:
-  exit_on_error: false
-```
-
-This tells Roast to:
-- Continue workflow execution even if the command fails
-- Capture the full output (stdout and stderr)
-- Append the exit status to the output
-
-## Output Format
-
-When a command fails with `exit_on_error: false`, the output will look like:
-
-```
-lib/example.rb:5:3: C: Style/StringLiterals: Prefer double-quoted strings
-  'hello'
-  ^^^^^^^
-[Exit status: 1]
-```
-
-This allows subsequent steps to process both the error output and the exit status.
-
-## Running the Example
-
-```bash
-roast execute workflow.yml path/to/file.rb
-```
-
-The workflow will:
-1. Run RuboCop on the file
-2. Continue even if RuboCop finds issues
-3. Analyze the linter output
-4. Apply fixes based on the analysis

data/examples/exit_on_error/analyze_lint_output/prompt.md

@@ -1,9 +0,0 @@
-The linter output from the previous step shows issues with the code.
-Please analyze the output and identify the specific problems that need to be fixed.
-
-Focus on:
-- Syntax errors
-- Style violations
-- Best practice violations
-
-Provide a structured list of issues found.

data/examples/exit_on_error/apply_fixes/prompt.md

@@ -1,2 +0,0 @@
-Based on the analysis, please generate the fixes for the identified issues.
-Use the CodingAgent tool to apply the necessary changes to the file.

data/examples/exit_on_error/workflow.yml

@@ -1,19 +0,0 @@
-name: Linting with Error Recovery
-tools:
-  - Roast::Tools::ReadFile
-  - Roast::Tools::WriteFile
-  - Roast::Tools::CodingAgent
-
-steps:
-  # Run linter on the file - may fail if there are syntax errors
-  - lint_check: $(rubocop {{file}})
-  
-  # Analyze linter output and fix issues even if linter failed
-  - analyze_lint_output
-  
-  # Apply fixes based on the analysis
-  - apply_fixes
-
-# Step configuration
-lint_check:
-  exit_on_error: false  # Continue even if rubocop exits with non-zero status

data/examples/grading/README.md

@@ -1,71 +0,0 @@
-# Test Grading Workflow
-
-This workflow acts as a senior software engineer and testing expert to evaluate the quality of test files based on best practices and guidelines.
-
-## Prerequisites
-
-This example uses `shadowenv` for environment management, which is specific to Shopify's development environment. If you're not using shadowenv, you'll need to adapt the commands to your own setup.
-
-### If you're using shadowenv:
-```bash
-brew install shadowenv
-```
-
-### If you're NOT using shadowenv:
-You'll need to modify the `run_coverage.rb` file to remove the shadowenv commands. Look for lines like:
-```ruby
-command = "shadowenv exec -- bundle exec ruby ..."
-```
-
-And change them to match your environment:
-```ruby
-# For standard Ruby/Bundler setup:
-command = "bundle exec ruby ..."
-
-# Or if you're using rbenv/rvm:
-command = "ruby ..."
-```
-
-## Usage
-
-```bash
-# Run the grading workflow on a test file
-roast execute examples/grading/workflow.yml path/to/your_test.rb
-```
-
-## How it Works
-
-1. **read_dependencies**: Analyzes the test file and its dependencies
-2. **run_coverage**: Executes the test with coverage tracking
-3. **generate_grades**: Evaluates test quality across multiple dimensions
-4. **verify_test_helpers**: Checks for proper test helper usage
-5. **verify_mocks_and_stubs**: Ensures appropriate use of test doubles
-6. **analyze_coverage**: Reviews code coverage metrics
-7. **generate_recommendations**: Provides improvement suggestions
-8. **calculate_final_grade**: Computes an overall grade (A-F scale)
-9. **format_result**: Formats the final output
-
-## Customization
-
-Feel free to adapt this workflow to your testing environment:
-
-- **Different test frameworks**: Modify `run_coverage.rb` to work with RSpec, Jest, pytest, etc.
-- **Coverage tools**: Replace the coverage command with your preferred tool (SimpleCov, Istanbul, Coverage.py)
-- **Grading criteria**: Adjust the prompts in each step to match your team's standards
-- **Environment setup**: Remove or replace shadowenv with your environment management tool
-
-## Example Output
-
-```
-========== TEST GRADE REPORT ==========
-Test file: test/example_test.rb
-
-FINAL GRADE:
-  Score: 85/100
-  Letter Grade: B
-
-RECOMMENDATIONS:
-- Add edge case testing for error conditions
-- Improve test descriptions for clarity
-- Consider extracting common setup to helper methods
-```

data/examples/grading/analyze_coverage/prompt.md

@@ -1,52 +0,0 @@
-<coverage_results>
-<%= workflow.output["run_coverage"] %>
-</coverage_results>
-
-Analyze the results and score them on a scale of 1-10 using the following rubrics:
-
-<line_coverage>
-0-1: Critical failure (0-20% coverage) - Core functionality remains completely untested
-2-3: Poor coverage (21-40%) - Major gaps; many key functions lack any testing
-4-5: Inadequate coverage (41-60%) - Several important code paths are not executed
-6-7: Moderate coverage (61-80%) - Notable gaps remain; some important functionality lacks coverage
-8-9: Good coverage (81-95%) - Only minor or edge case code paths remain untested
-10: Excellent coverage (96-100%)
-</line_coverage>
-
-<branch_coverage>
-0-1: Critical failure (0-20% branch coverage) - Almost no conditional branches are tested
-2-3: Poor coverage (21-40%) - Most conditional logic remains untested
-4-5: Inadequate coverage (41-60%) - Many conditions are only tested for one outcome
-6-7: Moderate coverage (61-80%) - Some conditions lack testing for all outcomes
-8-9: Good coverage (81-95%) - Most conditions are tested for most outcomes
-10: Excellent coverage (96-100%)
-</branch_coverage>
-
-<method_coverage>
-0-1: Critical failure (0-20% method coverage) - Most or core functionality methods are untested
-2-3: Poor coverage (21-40%) - Several public API methods remain untested
-4-5: Inadequate coverage (41-60%) - Some important public methods lack tests
-6-7: Moderate coverage (61-80%) - Notable gaps remain; some public methods may lack comprehensive testing
-8-9: Good coverage (81-95%) - Nearly all public methods are tested; private methods are mostly covered via public method tests
-10: Excellent coverage (96-100%)
-</method_coverage>
-
-RESPONSE FORMAT
-You must respond in JSON format within <json> XML tags. Example:
-
-<json>
-{
-  "method_coverage": {
-    "score": "10",
-    "justification": "The source file has 100% method coverage, indicating all methods are being tested."
-  },
-  "line_coverage": {
-    "score": 10,
-    "justification": "The source file has 100% line coverage, indicating all executable lines are tested."
-  },
-  "branch_coverage": {
-    "score": 8,
-    "justification": "The source file has 80% branch coverage, indicating some branches need testing."
-  }
-}
-</json>