roast-ai 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64b0bfad5bc7ce9abd2d750ff52695ba997a750556a403e3ab4fc449dfb28946
-  data.tar.gz: 526beebc0ca0697df5ce2f871468fff246440615634ae516439b4c0740f8ce90
+  metadata.gz: 28055339ac18d63a1abd7151943558a114df2e48930c63aa63c65536d193061b
+  data.tar.gz: c5be17b70caa32f73dca316ab4816d0b92c0c7121747b3e5492f58124e815f87
 SHA512:
-  metadata.gz: 0600537a7242638e683a884a0b22b4d5f7fd58bb02d0c7a04240c8720d197a1f4f5e2d5f44c1a7f0335506f7822b51b6c245fd1c5f25627c8a580319d63b1250
-  data.tar.gz: e368630d036c6c3ac6efe00d102ddbf89d438332916ed1adb5aa54fe6cb5f9b34f9adf637c6e36c5baab07015c6f0fb848f675476d4233accd005a98b9630642
+  metadata.gz: d5b300fd001d8cc55ecdb5751bc891840732f63be8e951e2c4333a178fde6c2197a2b0063f3add45b48e85251e9b2ee28119d237322bb8f89af86c2208345c1f
+  data.tar.gz: c579010aedef591cd1a72fb6cd34c15db38fc225550aa17a841397e5f8849c09c5f87cf81da3f04f2300c5dcac704ab2d8a0f78fe8fd443fabfe62e67780a015

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-06-04
+
+### Changed
+- **BREAKING**: Upgraded to Raix 1.0.0 (#141)
+  - Removed the deprecated `loop` parameter from chat_completion calls
+  - Raix 1.0 automatically continues after tool calls until providing a text response
+  - All chat completions now return strings (no longer arrays or complex structures)
+  - JSON responses are automatically parsed when `json: true` is specified
+- **BREAKING**: Removed configurable `loop` and `auto_loop` options from workflow configuration (#140)
+  - The `loop:` and `auto_loop:` YAML configuration options have been removed entirely
+  - Looping behavior is now automatic: always enabled when tools are present, disabled when no tools exist
+  - This simplifies the codebase and makes behavior more predictable
+  - To migrate: remove any `loop: true/false` or `auto_loop: true/false` settings from your workflow YAML files
+
+### Fixed
+- Enhanced boolean coercion to treat empty strings as false
+- Improved iterable coercion to handle JSON array strings
+- Fixed all tests to work with Raix 1.0's string-only responses
+
+## [0.2.3] - 2025-05-29
+
+### Fixed
+- Model inheritance for nested steps in iteration steps (#105)
+  - Nested steps within `repeat` and `each` blocks now properly inherit model configuration
+  - Configuration hierarchy works correctly: step-specific → workflow-level → default model
+  - Previously, nested steps always used the default model regardless of configuration
+
 ## [0.2.2] - 2025-05-29
 
 ### Added

data/CLAUDE.md

@@ -55,6 +55,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Guidance and Expectations
 
 - Do not decide unilaterally to leave code for the sake of "backwards compatibility"... always run those decisions by me first.
+- Don't ever commit and push changes unless directly told to do so
 
 ## Git Workflow Practices
 
@@ -165,4 +166,5 @@ gh pr diff {pr_number}
 18. Prioritize code readability while encouraging performance optimizations:
     - Avoid premature optimization outside of hot paths
     - Consider the tradeoff between readability and performance
-    - Suggest optimizations that improve both clarity and performance
+    - Suggest optimizations that improve both clarity and performance
+```

data/Gemfile

@@ -17,3 +17,4 @@ gem "rake", require: false
 gem "rubocop-shopify", require: false
 gem "vcr", require: false
 gem "webmock", require: false
+gem "minitest-rg"

data/Gemfile.lock

@@ -1,19 +1,20 @@
 PATH
   remote: .
   specs:
-    roast-ai (0.2.2)
+    roast-ai (0.3.0)
       activesupport (>= 7.0)
       cli-ui
       diff-lcs (~> 1.5)
       faraday-retry
       json-schema
-      raix (~> 0.8.6)
+      open_router (~> 0.3)
+      raix (~> 1.0)
       thor (~> 1.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.2.1)
+    activesupport (8.0.2)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -25,12 +26,13 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.2)
     cgi (0.4.2)
     cli-ui (2.3.1)
     coderay (1.1.3)
@@ -41,7 +43,7 @@ GEM
       rexml
     diff-lcs (1.6.1)
     dotenv (3.1.8)
-    drb (2.2.1)
+    drb (2.2.3)
     event_stream_parser (1.0.0)
     faraday (2.13.1)
       faraday-net_http (>= 2.0, < 3.5)
@@ -53,7 +55,6 @@ GEM
       net-http (>= 0.5.0)
     faraday-retry (2.3.1)
       faraday (~> 2.0)
-    ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     formatador (1.1.0)
@@ -75,7 +76,7 @@ GEM
     hashdiff (1.1.2)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    json (2.12.0)
+    json (2.12.2)
     json-schema (5.1.1)
       addressable (~> 2.8)
       bigdecimal (~> 3.1)
@@ -88,6 +89,8 @@ GEM
     lumberjack (1.2.10)
     method_source (1.1.0)
     minitest (5.25.5)
+    minitest-rg (5.3.0)
+      minitest (~> 5.0)
     mocha (2.7.1)
       ruby2_keywords (>= 0.0.5)
     multipart-post (2.4.1)
@@ -114,10 +117,11 @@ GEM
     public_suffix (6.0.1)
     racc (1.8.1)
     rainbow (3.1.1)
-    raix (0.8.6)
+    raix (1.0.0)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
       open_router (~> 0.2)
+      ostruct
       ruby-openai (~> 7)
     rake (13.2.1)
     rb-fsevent (0.11.2)
@@ -173,6 +177,7 @@ DEPENDENCIES
   dotenv
   guard
   guard-minitest
+  minitest-rg
   mocha
   rake
   roast-ai!

data/README.md

@@ -51,6 +51,10 @@ steps:
 analyze_coverage:
   model: gpt-4-turbo
   json: true
+
+# Step-specific config that specifies a custom path, not in the current directory
+generate_report:
+  path: ../reporting/generate_report
 ```
 
 Each step can have its own prompt file (e.g., `analyze_coverage/prompt.md`) and configuration. Steps can be run in parallel by nesting them in arrays:
@@ -78,7 +82,7 @@ steps:
 
 ## Try it
 
-If you don’t have one already, get an OpenAI key from [here](https://platform.openai.com/settings/organization/api-keys). You will need an account with a credit card, make sure that a basic completion works.
+If you don't have one already, get an OpenAI key from [here](https://platform.openai.com/settings/organization/api-keys). You will need an account with a credit card, make sure that a basic completion works.
 
 ```bash
 export OPENAI_API_KEY=sk-proj-....
@@ -169,7 +173,7 @@ Roast supports several types of steps:
    steps:
      - lint_check: $(rubocop {{file}})
      - fix_issues
-   
+
    # Step configuration
    lint_check:
      exit_on_error: false  # Continue workflow even if command fails
@@ -186,13 +190,13 @@ Roast supports several types of steps:
            - notify_team
          else:
            - run_development_setup
-     
+
      - verify_dependencies:
          unless: "$(bundle check)"
          then:
            - bundle_install: "$(bundle install)"
    ```
-   
+
    Conditions can be:
    - Ruby expressions: `if: "{{output['count'] > 5}}"`
    - Bash commands: `if: "$(test -f config.yml && echo true)"` (exit code 0 = true)
@@ -209,7 +213,7 @@ Roast supports several types of steps:
          steps:
            - analyze_file
            - Generate a report for {{current_file}}
-     
+
      # Repeat until a condition is met
      - improve_code:
          repeat:
@@ -219,12 +223,12 @@ Roast supports several types of steps:
              - run_tests
              - fix_issues
    ```
-   
+
    Each loops support:
    - Collections from Ruby expressions: `each: "{{[1, 2, 3]}}"`
    - Command output: `each: "$(ls *.rb)"`
    - Step references: `each: "file_list"`
-   
+
    Repeat loops support:
    - Until conditions: `until: "{{condition}}"`
    - Maximum iterations: `max_iterations: 10`
@@ -233,7 +237,7 @@ Roast supports several types of steps:
    ```yaml
    steps:
      - detect_language
-     
+
      - case: "{{ workflow.output.detect_language }}"
        when:
          ruby:
@@ -249,13 +253,13 @@ Roast supports several types of steps:
          - analyze_generic
          - generate_basic_report
    ```
-   
+
    Case expressions can be:
    - Workflow outputs: `case: "{{ workflow.output.variable }}"`
    - Ruby expressions: `case: "{{ count > 10 ? 'high' : 'low' }}"`
    - Bash commands: `case: "$(echo $ENVIRONMENT)"`
    - Direct values: `case: "production"`
-   
+
    The value is compared against each key in the `when` clause, and matching steps are executed.
    If no match is found, the `else` steps are executed (if provided).
 
@@ -266,6 +270,43 @@ Roast supports several types of steps:
    ```
    This creates a simple prompt-response interaction without tool calls or looping. It's detected by the presence of spaces in the step name and is useful for summarization or simple questions at the end of a workflow.
 
+#### Shared Configuration
+
+Roast supports sharing common configuration and steps across multiple workflows using a `shared.yml` file.
+
+1. Place a `shared.yml` file one level above your workflow directory
+2. Define YAML anchors for common configurations like tools, models or steps
+3. Reference these anchors in your workflow files using YAML alias syntax
+
+**Example structure:**
+```
+my_project/
+├── shared.yml          # Common configuration anchors
+└── workflows/
+    ├── analyze_code.yml
+    ├── generate_docs.yml
+    └── test_suite.yml
+```
+
+**Example `shared.yml`:**
+```yaml
+# Define common tools
+standard_tools: &standard_tools
+  - Roast::Tools::Grep
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+  - Roast::Tools::SearchFile
+```
+
+**Using in workflows:**
+```yaml
+name: Code Analysis Workflow
+tools: *standard_tools         # Reference shared tools
+
+steps:
+  ...
+```
+
 #### Data Flow Between Steps
 
 Roast handles data flow between steps in three primary ways:
@@ -542,6 +583,56 @@ Roast provides extensive instrumentation capabilities using ActiveSupport::Notif
 
 Roast provides several built-in tools that you can use in your workflows:
 
+#### Tool Configuration
+
+Tools can be configured using a hash format in your workflow YAML:
+
+```yaml
+tools:
+  - Roast::Tools::ReadFile        # No configuration needed
+  - Roast::Tools::Cmd:             # With configuration
+      allowed_commands:
+        - git
+        - npm
+        - yarn
+  - Roast::Tools::CodingAgent:     # Optional configuration
+      coding_agent_command: claude --model opus -p --allowedTools "Bash, Glob, Grep, LS, Read"
+```
+
+Currently supported configurations:
+- `Roast::Tools::Cmd` via `allowed_commands`: restricts which commands can be executed (defaults to: `pwd`, `find`, `ls`, `rake`, `ruby`, `dev`, `mkdir`)
+- `Roast::Tools::CodingAgent` via `coding_agent_command`: customizes the Claude Code CLI command used by the agent
+
+##### Cmd Tool Configuration
+
+The `Cmd` tool's `allowed_commands` can be configured in two ways:
+
+**1. Simple String Format** (uses default descriptions):
+```yaml
+tools:
+  - Roast::Tools::Cmd:
+      allowed_commands:
+        - pwd
+        - ls
+        - git
+```
+
+**2. Hash Format with Custom Descriptions**:
+```yaml
+tools:
+  - Roast::Tools::Cmd:
+      allowed_commands:
+        - pwd
+        - name: git
+          description: "git CLI - version control system with subcommands like status, commit, push"
+        - name: npm
+          description: "npm CLI - Node.js package manager with subcommands like install, run"
+        - name: docker
+          description: "Docker CLI - container platform with subcommands like build, run, ps"
+```
+
+Custom descriptions help the LLM understand when and how to use each command, making your workflows more effective.
+
 #### ReadFile
 
 Reads the contents of a file from the filesystem.
@@ -649,23 +740,43 @@ search_file(query: "class User", file_path: "app/models")
 
 #### Cmd
 
-Executes shell commands and returns their output.
+Executes shell commands with configurable restrictions. By default, only allows specific safe commands.
 
 ```ruby
-# Execute a simple command
+# Execute allowed commands (pwd, find, ls, rake, ruby, dev, mkdir by default)
+pwd(args: "-L")
+ls(args: "-la")
+ruby(args: "-e 'puts RUBY_VERSION'")
+
+# Or use the legacy cmd function with full command
 cmd(command: "ls -la")
+```
+
+- Commands are registered as individual functions based on allowed_commands configuration
+- Default allowed commands: pwd, find, ls, rake, ruby, dev, mkdir
+- Each command has built-in descriptions to help the LLM understand usage
+- Configurable via workflow YAML (see Tool Configuration section)
+
+#### Bash
 
-# With working directory specified
-cmd(command: "npm list", cwd: "/path/to/project")
+Executes shell commands without restrictions. **⚠️ WARNING: Use only in trusted environments!**
+
+```ruby
+# Execute any command - no restrictions
+bash(command: "curl https://api.example.com | jq '.data'")
 
-# With environment variables
-cmd(command: "deploy", env: { "NODE_ENV" => "production" })
+# Complex operations with pipes and redirects
+bash(command: "find . -name '*.log' -mtime +30 -delete")
+
+# System administration tasks
+bash(command: "ps aux | grep ruby | awk '{print $2}'")
 ```
 
-- Provides access to shell commands for more complex operations
-- Can specify working directory and environment variables
-- Captures and returns command output
-- Useful for integrating with existing tools and scripts
+- **No command restrictions** - full shell access
+- Designed for prototyping and development environments
+- Logs warnings by default (disable with `ROAST_BASH_WARNINGS=false`)
+- Should NOT be used in production or untrusted contexts
+- See `examples/bash_prototyping/` for usage examples
 
 #### CodingAgent
 
@@ -683,6 +794,64 @@ coding_agent(
 - Useful for tasks that require deep code understanding or multi-step changes
 - Can work across multiple files and languages
 
+### MCP (Model Context Protocol) Tools
+
+Roast supports MCP tools, allowing you to integrate external services and tools through the Model Context Protocol standard. MCP enables seamless connections to databases, APIs, and specialized tools.
+
+#### Configuring MCP Tools
+
+MCP tools are configured in the `tools` section of your workflow YAML alongside traditional Roast tools:
+
+```yaml
+tools:
+  # Traditional Roast tools
+  - Roast::Tools::ReadFile
+
+  # MCP tools with SSE (Server-Sent Events)
+  - Documentation:
+      url: https://gitmcp.io/myorg/myrepo/docs
+      env:
+        - "Authorization: Bearer {{env.API_TOKEN}}"
+
+  # MCP tools with stdio
+  - GitHub:
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
+      env:
+        GITHUB_PERSONAL_ACCESS_TOKEN: "{{env.GITHUB_TOKEN}}"
+      only:
+        - search_repositories
+        - get_issue
+        - create_issue
+```
+
+#### SSE MCP Tools
+
+Connect to HTTP endpoints implementing the MCP protocol:
+
+```yaml
+- Tool Name:
+    url: https://example.com/mcp-endpoint
+    env:
+      - "Authorization: Bearer {{resource.api_token}}"
+    only: [function1, function2]  # Optional whitelist
+    except: [function3]           # Optional blacklist
+```
+
+#### Stdio MCP Tools
+
+Connect to local processes implementing the MCP protocol:
+
+```yaml
+- Tool Name:
+    command: docker
+    args: ["run", "-i", "--rm", "ghcr.io/example/mcp-server"]
+    env:
+      API_KEY: "{{env.API_KEY}}"
+```
+
+See the [MCP tools example](examples/mcp/) for complete documentation and more examples.
+
 ### Custom Tools
 
 You can create your own tools using the [Raix function dispatch pattern](https://github.com/OlympiaAI/raix-rails?tab=readme-ov-file#use-of-toolsfunctions). Custom tools should be placed in `.roast/initializers/` (subdirectories are supported):

data/examples/bash_prototyping/README.md

@@ -0,0 +1,53 @@
+# Bash Tool Examples
+
+This directory contains example workflows demonstrating the Bash tool, which provides unrestricted command execution for prototyping scenarios.
+
+## ⚠️ Security Warning
+
+The Bash tool executes commands without any restrictions. Only use it in:
+- Development environments
+- Trusted contexts
+- Prototyping scenarios where you explicitly want unrestricted access
+
+**Never use the Bash tool in production workflows or with untrusted input!**
+
+## Examples
+
+### 1. System Analysis Workflow (`system_analysis.yml`)
+
+Demonstrates using Bash for system inspection and analysis tasks that would be restricted by the Cmd tool.
+
+### 2. API Testing Workflow (`api_testing.yml`)
+
+Shows how to use Bash for making API calls with curl and processing responses with jq.
+
+### 3. DevOps Automation (`devops_workflow.yml`)
+
+Example of using Bash for DevOps tasks like container management and log analysis.
+
+## Disabling Warnings
+
+By default, the Bash tool logs warnings about unrestricted execution. To disable these warnings:
+
+```bash
+export ROAST_BASH_WARNINGS=false
+roast execute workflow.yml
+```
+
+## Best Practices
+
+1. **Use Cmd tool when possible**: If your commands fit within Cmd's allowed list, use it instead
+2. **Validate inputs**: Always validate any user input before passing to Bash
+3. **Limit scope**: Use the most restrictive tool that meets your needs
+4. **Document risks**: Clearly document when and why Bash tool is necessary
+5. **Environment isolation**: Run Bash workflows in isolated environments when possible
+
+## Comparison with Cmd Tool
+
+| Feature | Cmd Tool | Bash Tool |
+|---------|----------|-----------|
+| Command restrictions | Yes (configurable) | No |
+| Default allowed commands | pwd, find, ls, rake, ruby, dev, mkdir | All commands |
+| Security warnings | No | Yes (can be disabled) |
+| Recommended for production | Yes | No |
+| Use case | General automation | Prototyping & development |

data/examples/bash_prototyping/analyze_network/prompt.md

@@ -0,0 +1,13 @@
+# Analyze Network Configuration
+
+Use the bash tool to gather network information:
+
+1. Check network interfaces (ifconfig or ip addr)
+2. Display routing table (netstat -nr or ip route)
+3. Check listening ports (netstat -an | grep LISTEN or lsof -i -P | grep LISTEN)
+4. Test DNS resolution (nslookup example.com or dig example.com)
+5. Check current network connections
+
+Provide a summary of the network configuration and any interesting findings.
+
+Note: Some commands may require different syntax on macOS vs Linux.

data/examples/bash_prototyping/analyze_system/prompt.md

@@ -0,0 +1,11 @@
+# Analyze System Information
+
+Use the bash tool to gather system information including:
+
+1. Operating system details (uname -a)
+2. Current disk usage (df -h)
+3. Memory information (if available via free -m on Linux or vm_stat on macOS)
+4. Current user and groups (whoami, groups)
+5. Environment variables (env | grep -E "PATH|HOME|USER")
+
+Gather this information and provide a summary of the system's current state.

data/examples/bash_prototyping/api_testing.yml

@@ -0,0 +1,14 @@
+name: API Testing with Bash
+model: gpt-4o-mini
+tools:
+  - Roast::Tools::Bash
+  - Roast::Tools::WriteFile
+
+# Demonstrates using Bash for API testing with curl and jq
+# These commands would be restricted by the Cmd tool
+
+steps:
+  - test_public_api
+  - process_json_response
+  - test_multiple_endpoints
+  - generate_api_report

data/examples/bash_prototyping/check_processes/prompt.md

@@ -0,0 +1,11 @@
+# Check Running Processes
+
+Use the bash tool to analyze running processes:
+
+1. List all processes (ps aux or ps -ef)
+2. Find the top 5 CPU-consuming processes
+3. Find the top 5 memory-consuming processes
+4. Check if any specific development services are running (like databases, web servers)
+5. Count total number of processes
+
+Note: The exact commands may vary between macOS and Linux. Use appropriate commands for the detected OS.

data/examples/bash_prototyping/generate_report/prompt.md

@@ -0,0 +1,16 @@
+# Generate System Analysis Report
+
+Based on all the information gathered in previous steps:
+
+1. Create a comprehensive markdown report summarizing:
+   - System specifications and OS details
+   - Resource usage (CPU, memory, disk)
+   - Active processes and services
+   - Network configuration
+   - Any potential issues or interesting findings
+
+2. Save the report to `system_analysis_report.md` using the write_file tool
+
+3. Include timestamps and organize the information in a clear, readable format
+
+The report should be suitable for sharing with other developers or for documentation purposes.

data/examples/bash_prototyping/process_json_response/prompt.md

@@ -0,0 +1,24 @@
+# Process JSON Responses
+
+Use bash with jq (if available) to process JSON responses:
+
+1. First check if jq is installed:
+   ```bash
+   which jq
+   ```
+
+2. If jq is available, use it to parse JSON:
+   ```bash
+   curl -s https://api.github.com/users/github | jq '.name, .public_repos'
+   ```
+
+3. If jq is not available, use alternative methods like:
+   - grep with regular expressions
+   - sed/awk for parsing
+   - Python one-liners if Python is available
+
+4. Extract specific fields from the API responses
+5. Count items in arrays
+6. Filter data based on conditions
+
+Show different approaches for JSON processing depending on available tools.

data/examples/bash_prototyping/system_analysis.yml

@@ -0,0 +1,14 @@
+name: System Analysis with Bash
+model: gpt-4o-mini
+tools:
+  - Roast::Tools::Bash
+  - Roast::Tools::WriteFile
+
+# This workflow demonstrates using Bash for system analysis tasks
+# that would be restricted by the Cmd tool
+
+steps:
+  - analyze_system
+  - check_processes
+  - analyze_network
+  - generate_report

data/examples/bash_prototyping/test_public_api/prompt.md

@@ -0,0 +1,22 @@
+# Test Public API Endpoints
+
+Use the bash tool to test various public APIs:
+
+1. Test GitHub API:
+   ```bash
+   curl -s https://api.github.com/users/github
+   ```
+
+2. Test a public JSON placeholder API:
+   ```bash
+   curl -s https://jsonplaceholder.typicode.com/posts/1
+   ```
+
+3. Check response headers:
+   ```bash
+   curl -I https://api.github.com
+   ```
+
+4. Test with different HTTP methods if appropriate
+
+Analyze the responses and note the structure of the returned data.