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.