roast

Open source

Structured AI workflows made easy

1.2K stars0 likes0 views

About

Structured AI workflows made easy

Roast

A Ruby-based domain-specific language for creating structured AI workflows. Build complex AI-powered automation with simple, declarative Ruby syntax.

Overview

Roast lets you orchestrate AI workflows by combining "cogs" - building blocks that interact with LLMs, run code, execute commands, and process data. Write workflows that:

Chain AI steps together - Output from one cog flows seamlessly to the next
Run coding agents locally - Full filesystem access with Pi, Claude Code, or other providers
Process collections - Map operations over arrays with serial or parallel execution
Control flow intelligently - Conditional execution, iteration, and error handling
Reuse workflow components - Create modular, parameterized scopes

Quick Example

ruby

# analyze_codebase.rb
execute do
  # Get recent changes
  cmd(:recent_changes) { "git diff --name-only HEAD~5..HEAD" }

  # AI agent analyzes the code
  agent(:review) do
    files = cmd!(:recent_changes).lines
    <<~PROMPT
      Review these recently changed files for potential issues:
      #{files.join("\n")}

      Focus on security, performance, and maintainability.
    PROMPT
  end

  # Summarize for stakeholders
  chat(:summary) do
    "Summarize this for non-technical stakeholders:\n\n#{agent!(:review).response}"
  end
end

Run with:

bash

bin/roast execute analyze_codebase.rb

Core Cogs

chat - Send prompts to cloud-based LLMs (OpenAI, Anthropic, Perplexity & Gemini)
agent - Run local coding agents with filesystem access (Pi CLI, Claude Code CLI, etc.)
ruby - Execute custom Ruby code within workflows
cmd - Run shell commands and capture output
map - Process collections in serial or parallel
repeat - Iterate until conditions are met
call - Invoke reusable workflow scopes

Installation

bash

gem install roast-ai

Or add to your Gemfile:

ruby

gem 'roast-ai'

Requirements

Ruby 3.0+
API keys or local credentials for your AI provider
Pi CLI installed (for the default agent provider)

Provider Configuration

Roast provider settings are configured in workflow config blocks. To change the default chat provider without editing each workflow, set the ROAST_DEFAULT_CHAT_PROVIDER environment variable (e.g. export ROAST_DEFAULT_CHAT_PROVIDER=anthropic). To change the default agent provider, set ROAST_DEFAULT_AGENT_PROVIDER. A provider set in a workflow's config always takes precedence over these variables, and an invalid value raises an error.

Chat cog

The chat cog supports OpenAI, Anthropic, Perplexity, and Gemini. It defaults to :openai (override globally with ROAST_DEFAULT_CHAT_PROVIDER). Each provider reads its API key from a provider-specific environment variable:

Provider	API key env var	Base URL env var
`:openai`	`OPENAI_API_KEY`	`OPENAI_API_BASE`
`:anthropic`	`ANTHROPIC_API_KEY`	`ANTHROPIC_API_BASE`
`:perplexity`	`PERPLEXITY_API_KEY`	—
`:gemini`	`GEMINI_API_KEY`	`GEMINI_API_BASE`

You can configure the provider directly in a workflow:

ruby

config do
  chat do
    provider :anthropic
    model "claude-haiku-4-5"
  end
end

Agent cog

The agent cog runs local agent CLIs. It defaults to :pi (override globally with ROAST_DEFAULT_AGENT_PROVIDER) and currently supports:

:claude - Claude Code CLI
:pi - Pi CLI

Select a provider in the workflow config:

ruby

config do
  agent do
    provider :pi
  end
end

Agent providers must be installed and authenticated according to their own CLI requirements.

Configuration

Roast currently supports four LLM providers for the chat cog: OpenAI, Anthropic, Perplexity and Gemini.

Set OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY and/or GEMINI_API_KEY in your environment.
Optionally set OPENAI_API_BASE, ANTHROPIC_API_BASE and/or GEMINI_API_BASE to override the default endpoint. Perplexity does not support base URL override.

The default model is set per-provider and can only be overridden inside a config block. See the tutorial for examples.

The agent cog is powered by the Pi CLI by default, which handles its own authentication.