Streamlined AI Workflows with Roast: A Structured Approach by Shopify

Roast is a convention-oriented framework for creating structured AI workflows, developed and maintained by Shopify's Augmented Engineering team. It provides a structured, declarative approach to building AI workflows, focusing on convention over configuration. Roast supports various features, including:

Convention over configuration

  1. Define powerful workflows using simple YAML configuration files and ERB-supported prompts in markdown.
  2. Built-in tools: Roast offers ready-to-use tools for file operations, search, and AI interactions.
  3. Ruby integration: Users can write custom steps in Ruby using a clean, extensible architecture.
  4. Shared context: Each step shares its conversation transcript with its parent workflow by default.
  5. Step customization: Steps can be fully configured with their own AI models and parameters.
  6. Session replay: Rerun previous sessions starting at a specified step to accelerate development time.
  7. Parallel execution: Run multiple steps concurrently to speed up workflow execution.

A simple workflow example in Roast is an analysis of test files using the 'gpt-4' model and built-in tools like Roast::Tools::ReadFile and Roast::Tools::Grep. Each step can have its own prompt file and configuration, and steps can be run in parallel by nesting them in arrays. Workflows can also include steps that run bash commands, use interpolation with {{}} syntax, and have simple inlined prompts as a natural language string.

Roast

GitHub - Structured AI workflows made easy

Features

Roast is a convention-oriented framework for creating structured AI workflows, maintained by the Augmented Engineering team at Shopify. Here are some reasons why you should use Roast:

  • Convention over configuration: Define powerful workflows using simple YAML configuration files and prompts written in markdown (with ERB support)
  • Built-in tools: Ready-to-use tools for file operations, search, and AI interactions
  • Ruby integration: When prompts aren't enough, write custom steps in Ruby using a clean, extensible architecture
  • Shared context: Each step shares its conversation transcript with its parent workflow by default
  • Step customization: Steps can be fully configured with their own AI models and parameters
  • Session replay: Rerun previous sessions starting at a specified step to speed up development time
  • Parallel execution: Run multiple steps concurrently to speed up workflow execution
  • Function caching: Flexibly cache the results of tool function calls to speed up workflows
  • Extensive instrumentation: Monitor and track workflow execution, AI calls, and tool usage

Getting Started

To use Roast, follow these steps:

  1. Create a workflow YAML file defining your steps and tools
  2. Create prompt files for each step (e.g., step_name/prompt.md)
  3. Run the workflow:
roast execute workflow.yml target_file.rb

or

roast execute workflow.yml
``` for a targetless workflow (API calls, data generation, etc.)

## Understanding Workflows

In Roast, workflows maintain a single conversation with the AI model throughout execution. Each step represents one or more user-assistant interactions within this conversation, with optional tool calls. Steps naturally build upon each other through the shared context.

### Step Types

Roast supports several types of steps:

- Standard step: References a directory containing at least a `prompt.md` and optional `output.txt` template.
- Custom step: Implement a custom step as a Ruby class, optionally extending `Roast::Workflow::BaseStep`.
- Parallel steps: Groups of steps executed concurrently
- Command execution step: Executes shell commands directly
- Raw prompt step: Simple text prompts for the model without tools

## Data Flow Between Steps

Roast handles data flow between steps in three primary ways:

- **Conversation Context (Implicit)**: The LLM naturally remembers the entire conversation history, including all previous prompts and responses.
- **Output Hash (Explicit)**: Each step's result is automatically stored in the `workflow.output` hash using the step name as the key.
- **Interpolation (Dynamic)**: Use `{{expression}}` syntax to inject values from the workflow context directly into step names, commands, or prompt text.

## Target Option (`-t`, `--target`)

Roast accepts various target formats:

- Single file path
- Directory path
- Glob patterns
- URL as target
- API configuration (Fetch API-style)
- Shell command execution with `$(...)`
- Git integration examples

## Targetless Workflows

Roast also supports workflows that don't operate on a specific pre-defined set of target files:

- API-driven workflows
- Content generation workflows
- Report creation workflows
- Interactive tools
- Scheduled automation tasks

## Global Model Configuration

You can set a default model for all steps in your workflow by specifying the `model` parameter at the top level.

Individual steps can override this setting with their own model parameter.

### API Provider Configuration

Roast supports both OpenAI and OpenRouter as API providers.

## Dynamic API Tokens

Roast allows you to dynamically fetch API tokens using shell commands directly in your workflow configuration.

## Template Output with ERB

Each step can have an `output.txt` file that uses ERB templating to format the final output.

## Advanced Features

### Instrumentation

Roast provides extensive instrumentation capabilities using ActiveSupport::Notifications.

### Built-in Tools

Roast provides several built-in tools that you can use in your workflows:

- `ReadFile`
- `WriteFile`
- `UpdateFiles`
- `Grep`
- `SearchFile`
- `Cmd`
- `CodingAgent`

### Custom Tools

You can create your own tools using the Raix function dispatch pattern.

## Project-specific Configuration

You can extend Roast with project-specific configuration by creating initializers in `.roast/initializers/`.

## Installation

```bash
gem install roast-ai
``` or add to your `Gemfile`:

```ruby
gem 'roast-ai'

Development

After checking out the repo, run bundle install to install dependencies. Then, run bundle exec rake to run the tests and linter.