roast-ai 1.0.2 → 1.2.0

data/sorbet/rbi/shims/lib/roast/execution_context.rbi

@@ -320,7 +320,7 @@ module Roast
     # ### See Also
     # - `chat` - Pure LLM interaction without local system access
     #
-    #: (?Symbol?) {(Roast::Cogs::Agent::Input, untyped, Integer) [self: Roast::CogInputContext] -> (String | void)} -> void
+    #: (?Symbol?) {(Roast::Cogs::Agent::Input, untyped, Integer) [self: Roast::CogInputContext] -> top} -> void
     def agent(name = nil, &block); end
 
     # Perform pure LLM interaction
@@ -376,7 +376,7 @@ module Roast
     # ### See Also
     # - `agent` - Run a coding agent with local filesystem access
     #
-    #: (?Symbol?) {(Roast::Cogs::Chat::Input, untyped, Integer) [self: Roast::CogInputContext] -> (String | void)} -> void
+    #: (?Symbol?) {(Roast::Cogs::Chat::Input, untyped, Integer) [self: Roast::CogInputContext] -> top} -> void
     def chat(name = nil, &block); end
 
     # Execute a shell command
@@ -438,7 +438,7 @@ module Roast
     # ### See Also
     # - `ruby` - Evaluate Ruby code within the workflow context
     #
-    #: (?Symbol?) {(Roast::Cogs::Cmd::Input, untyped, Integer) [self: Roast::CogInputContext] -> (String | Array[String] | void)} -> void
+    #: (?Symbol?) {(Roast::Cogs::Cmd::Input, untyped, Integer) [self: Roast::CogInputContext] -> top} -> void
     def cmd(name = nil, &block); end
 
     # Evaluate Ruby code within the workflow context

data/tutorial/01_your_first_workflow/README.md

@@ -58,7 +58,7 @@ That's it! Everything happens inside the `execute do ... end` block.
 
 ## Your First Chat Cog
 
-The `chat` cog sends a prompt to a cloud-based LLM and gets a response back. Here's a simplest example:
+The `chat` cog sends a prompt to a cloud-based LLM and gets a response back. Here's a simple example:
 
 ```ruby
 execute do
@@ -106,7 +106,7 @@ block:
 config do
   chat do
     model "gpt-4o-mini" # Use OpenAI's fast model
-    provider :openai # Use OpenAI (can also be :anthropic)
+    provider :openai # Use OpenAI (can also be :anthropic, :perplexity or :gemini)
     show_prompt! # Display the prompt before sending
   end
 end
@@ -125,15 +125,19 @@ end
 Common options you can set:
 
 - `model "name"` - Which LLM model to use
-    - OpenAI: "gpt-4o", "gpt-4o-mini", "gpt-4-turbo"
-    - Anthropic: "claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022"
+    - OpenAI: "gpt-4o-mini" (default), "gpt-4o", "gpt-5.5", etc.
+    - Anthropic: "claude-haiku-4-5" (default), "claude-sonnet-4-6", "claude-opus-4-7", etc.
+    - Perplexity: "sonar" (default), "sonar-pro", "sonar-deep-research", etc.
+    - Gemini: "gemini-3.1-flash-lite" (default), "gemini-3-flash-preview", "gemini-3.1-pro-preview", etc.
 - `provider :name` - Which LLM provider
-    - `:openai` or `:anthropic`
+    - `:openai`, `:anthropic`, `:perplexity` or `:gemini`
 - `show_prompt!` - Display the prompt being sent
 - `show_response!` - Display the response (on by default)
 - `show_stats!` - Display token usage statistics (on by default)
 - `no_display!` - Turn off all output (useful when you just want to pass the output to a subsequent cog)
 
+**Note:** Unlike the api key and api base url, the model is **not** environment-controlled. You must set it inside a `config` block (shown above). The same applies to `provider` and other DSL options.
+
 ## Running the Workflows
 
 To run any workflow in this chapter:

data/tutorial/01_your_first_workflow/configured_chat.rb

@@ -10,7 +10,7 @@ config do
   # Configure all chat cogs in this workflow
   chat do
     model "gpt-4o-mini"      # Use OpenAI's fast, cost-effective model
-    provider :openai         # Use OpenAI (alternative: :anthropic)
+    provider :openai         # Use OpenAI (alternative: :anthropic, :perplexity or :gemini)
     show_prompt!             # Display the prompt before sending it
     show_response!           # Display the response (this is the default)
     show_stats!              # Display token usage statistics (default)

data/tutorial/02_chaining_cogs/README.md

@@ -42,11 +42,11 @@ end
 ```
 
 This returns the cog's output, or `nil` if the cog didn't run (we'll learn about conditionally skipping steps in a later
-lesson.
+lesson).
 
 ### Different Output Methods
 
-Different cog types provide different types of output. Here are few highlights:
+Different cog types provide different types of output. Here are a few highlights:
 
 - `chat(:name).response` - The text response from a chat cog
 - `agent(:name).response` - The text response from an agent cog

data/tutorial/02_chaining_cogs/code_review.rb

@@ -8,7 +8,7 @@
 
 config do
   agent do
-    model "claude-3-5-haiku-20241022"
+    model "claude-haiku-4-5-20251001"
     provider :claude
   end
 

data/tutorial/02_chaining_cogs/session_resumption.rb

@@ -10,7 +10,7 @@ config do
     show_stats!
   end
   chat(:recall_code) do
-    model "gpt-4.1-nano"
+    model "gpt-5.4-nano"
   end
   agent do
     model "haiku"

data/tutorial/03_targets_and_params/README.md

@@ -177,7 +177,7 @@ execute do
   agent(:process) do
     files = targets.join("\n")
     format = kwarg(:format) || "detailed"
-    "Process these files and provide a #{format} report:\n#{files}) "
+    "Process these files and provide a #{format} report:\n#{files} "
   end
 
   cmd(:grep_pattern) do

data/tutorial/04_configuration_options/README.md

@@ -45,7 +45,7 @@ config do
   end
 
   agent do
-    model "claude-3-5-haiku-20241022"
+    model "claude-haiku-4-5"
     provider :claude
   end
 end
@@ -125,7 +125,7 @@ the prompt, response, usage statistics, and (for the agent cog) incremental prog
 For the `cmd` cog, you can control the display of standard output and standard error.
 
 - `show_stdout!` / `no_show_stdout!` - Control stdout display
-- `show_stderr!` / `no_show_stderr!` - Control stdout display
+- `show_stderr!` / `no_show_stderr!` - Control stderr display
 
 And for all cog types, you can quickly apply some typical configurations
 

data/tutorial/08_iterative_workflows/README.md

@@ -89,7 +89,7 @@ execute(:process_numbers) do
   ruby(:check) do |_, _, index|
     # Skip processing for multiples of 3
     if index % 3 == 0
-      puts "  Skipping every third 3 iteration"
+      puts "  Skipping every third iteration"
       next!
     end
     puts "Processing #{index}"

data/tutorial/README.md

@@ -14,7 +14,7 @@ run coding agents, process data, and so much more.
 
 - Ruby installed (3.4.2+)
 - Roast gem installed
-- API keys for your AI providers of choice (to use LLM chat)
+- API keys for your AI provider (see [Configuration](https://github.com/Shopify/roast/blob/main/README.md#configuration) for setup)
 - Claude Code CLI installed and configured (to use coding agents)
 
 ## How to Use This Tutorial

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roast-ai
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Shopify
@@ -57,14 +57,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: type_toolkit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -112,11 +126,8 @@ files:
 - bin/srb-rbi
 - bin/tapioca
 - dev.yml
-- docs/AGENT_STEPS.md
-- docs/INSTRUMENTATION.md
-- docs/ITERATION_SYNTAX.md
-- docs/VALIDATION.md
 - examples/agent_sessions.rb
+- examples/agent_with_multiple_prompts.rb
 - examples/async_cogs.rb
 - examples/async_cogs_complex.rb
 - examples/call.rb
@@ -152,6 +163,7 @@ files:
 - examples/shell_sanitization.rb
 - examples/simple_agent.rb
 - examples/simple_chat.rb
+- examples/simple_pi_agent.rb
 - examples/simple_repeat.rb
 - examples/skip.rb
 - examples/step_communication.rb
@@ -160,10 +172,14 @@ files:
 - examples/temporary_directory.rb
 - examples/working_directory.rb
 - exe/roast
-- internal/documentation/architectural-notes.md
-- internal/documentation/doc-comments-external.md
-- internal/documentation/doc-comments-internal.md
-- internal/documentation/doc-comments.md
+- internal/documentation/comments/architectural-notes.md
+- internal/documentation/comments/doc-comments-external.md
+- internal/documentation/comments/doc-comments-internal.md
+- internal/documentation/comments/doc-comments.md
+- internal/rubocop/cop/roast/no_test_class_nesting.rb
+- internal/rubocop/rubocop-roast.yml
+- internal/workflows/maintenance/branch_docs_impact.rb
+- internal/workflows/maintenance/deprecated_models_docs_updater.rb
 - lib/roast-ai.rb
 - lib/roast.rb
 - lib/roast/cli.rb
@@ -195,6 +211,10 @@ files:
 - lib/roast/cogs/agent/providers/claude/messages/user_message.rb
 - lib/roast/cogs/agent/providers/claude/tool_result.rb
 - lib/roast/cogs/agent/providers/claude/tool_use.rb
+- lib/roast/cogs/agent/providers/pi.rb
+- lib/roast/cogs/agent/providers/pi/messages/tool_call_message.rb
+- lib/roast/cogs/agent/providers/pi/messages/tool_result_message.rb
+- lib/roast/cogs/agent/providers/pi/pi_invocation.rb
 - lib/roast/cogs/agent/stats.rb
 - lib/roast/cogs/agent/usage.rb
 - lib/roast/cogs/chat.rb
@@ -215,7 +235,6 @@ files:
 - lib/roast/execution_manager.rb
 - lib/roast/log.rb
 - lib/roast/log_formatter.rb
-- lib/roast/nil_assertions.rb
 - lib/roast/output_router.rb
 - lib/roast/system_cog.rb
 - lib/roast/system_cog/params.rb
@@ -299,9 +318,10 @@ files:
 - sorbet/rbi/gems/rake@13.3.0.rbi
 - sorbet/rbi/gems/rb-fsevent@0.11.2.rbi
 - sorbet/rbi/gems/rb-inotify@0.11.1.rbi
-- sorbet/rbi/gems/rbi@0.3.6.rbi
-- sorbet/rbi/gems/rbs@3.9.4.rbi
+- sorbet/rbi/gems/rbi@0.3.9.rbi
+- sorbet/rbi/gems/rbs@4.0.0.dev.5.rbi
 - sorbet/rbi/gems/regexp_parser@2.10.0.rbi
+- sorbet/rbi/gems/require-hooks@0.2.3.rbi
 - sorbet/rbi/gems/rexml@3.4.2.rbi
 - sorbet/rbi/gems/rubocop-ast@1.45.1.rbi
 - sorbet/rbi/gems/rubocop-shopify@2.17.1.rbi
@@ -315,11 +335,13 @@ files:
 - sorbet/rbi/gems/simplecov-html@0.13.2.rbi
 - sorbet/rbi/gems/simplecov@0.22.0.rbi
 - sorbet/rbi/gems/simplecov_json_formatter@0.1.4.rbi
-- sorbet/rbi/gems/spoom@1.6.3.rbi
+- sorbet/rbi/gems/spoom@1.7.11.rbi
 - sorbet/rbi/gems/sqlite3@2.9.0.rbi
-- sorbet/rbi/gems/tapioca@0.16.11.rbi
+- sorbet/rbi/gems/tapioca@0.17.10.rbi
 - sorbet/rbi/gems/thor@1.4.0.rbi
 - sorbet/rbi/gems/traces@0.18.2.rbi
+- sorbet/rbi/gems/tsort@0.2.0.rbi
+- sorbet/rbi/gems/type_toolkit@0.0.5.rbi
 - sorbet/rbi/gems/tzinfo@2.0.6.rbi
 - sorbet/rbi/gems/unicode-display_width@3.1.4.rbi
 - sorbet/rbi/gems/unicode-emoji@4.0.4.rbi
@@ -384,7 +406,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.14
 specification_version: 4
 summary: A framework for executing structured AI workflows in Ruby
 test_files: []

data/docs/AGENT_STEPS.md

@@ -1,288 +0,0 @@
-# Agent Steps in Roast
-
-Agent steps provide a way to send prompts directly to a coding agent (like Claude Code) without going through the standard LLM translation layer. This document explains when and how to use agent steps effectively.
-
-## What are Agent Steps?
-
-Agent steps are denoted by prefixing a step name with `^`. They bypass the normal LLM processing and send your prompt content directly to the CodingAgent tool.
-
-```yaml
-steps:
-  # File-based prompts
-  - analyze_code       # Regular step - processed by LLM first
-  - ^implement_fix     # Agent step - direct to CodingAgent
-  
-  # Inline prompts
-  - Analyze the code quality and suggest improvements          # Regular inline
-  - ^Fix all ESLint errors and apply Prettier formatting       # Agent inline
-```
-
-Both file-based prompts (with directories like `implement_fix/prompt.md`) and inline prompts (text with spaces) are supported.
-
-## Agent Step Configuration Options
-
-Agent steps support two special configuration options:
-
-### `continue` (boolean, default: false)
-When set to `true`, the agent continues from its previous session instead of starting fresh. This is useful for iterative development where you want the agent to maintain context across multiple steps.
-
-### `include_context_summary` (boolean, default: false)
-When set to `true`, the agent receives an AI-generated summary of the workflow context as a system directive. This summary is intelligently tailored to the agent's upcoming task, including only relevant information from previous steps. The summary is generated by analyzing:
-- The agent's prompt to understand what context would be helpful
-- Previous step outputs and their relevance to the current task
-- Workflow description and configuration
-- Current working directory
-
-This helps the agent understand what has been done so far without overwhelming it with irrelevant details. NOTE: Without this option, the agent relies solely on what it is instructed to do either by the prompt or your specific step instructions.
-
-```yaml
-steps:
-  - analyze_code
-  - implement_fix: ^Fix the issues identified in the analysis
-  - add_tests: ^Prepare and publish PR
-
-implement_fix:
-  include_context_summary: true  # Include a summary of the workflow context so far
-
-add_tests:
-  continue: true # does not need context since is continuing from the previous step
-```
-
-## When to Use Agent Steps
-
-### Use Agent Steps When:
-
-1. **You need precise control over tool usage**
-   - When you want to ensure specific tools are used in a particular way
-   - When the task requires exact file manipulations or code transformations
-
-2. **Complex multi-file operations**
-   - When coordinating changes across multiple files
-   - When the operation requires specific sequencing of edits
-
-3. **Performance optimization**
-   - When you want to skip the LLM interpretation layer
-   - For well-defined tasks that don't need additional context
-
-### Use Regular Steps When:
-
-1. **You need natural language processing**
-   - When the prompt benefits from LLM interpretation
-   - When you want the LLM to add context or reasoning
-
-2. **Flexible, adaptive responses**
-   - When the exact approach might vary based on context
-   - When you want the LLM to make judgment calls
-
-## Practical Examples
-
-### Example 1: Database Migration
-
-**Regular Step (analyze_migration/prompt.md):**
-```markdown
-Look at the user's database schema and determine what migrations might be needed to support the new features they've described. Consider best practices for database design.
-```
-
-This benefits from LLM interpretation because:
-- It needs to understand "best practices" in context
-- It should make judgments about schema design
-- The approach varies based on the specific features
-
-**Agent Step (^apply_migration/prompt.md):**
-```markdown
-Create a new migration file with the following specifications:
-
-1. Create a new migration file: db/migrate/{{timestamp}}_add_user_preferences.rb
-2. The migration must include:
-   - Add column :users, :preferences, :jsonb, default: {}
-   - Add index :users, :preferences, using: :gin
-   - Add column :users, :notification_settings, :jsonb, default: {}
-3. Ensure proper up/down methods
-4. Follow Rails migration conventions exactly
-```
-
-This is better as an agent step because:
-- The instructions are precise and technical
-- No interpretation needed - just execution of steps known beforehand
-
-### Example 2: Code Refactoring
-
-**Regular Step (identify_code_smells/prompt.md):**
-```markdown
-Review the provided code and identify any code smells or anti-patterns. Consider things like:
-- Long methods that do too much
-- Duplicated code
-- Poor naming
-- Tight coupling
-- Missing abstractions
-
-Explain why each identified issue is problematic.
-```
-
-This works well as a regular step because it requires judgment and explanation.
-
-**Agent Step (^extract_method/prompt.md):**
-```markdown
-Extract the authentication logic from UserController#create into a separate method:
-
-1. Read file: app/controllers/user_controller.rb
-2. Find the code block from line 15-28 (the authentication logic)
-3. Create a new private method called `authenticate_user_params`
-4. Move the authentication logic to this new method
-5. Replace the original code with a call to the new method
-6. Ensure all variables are properly passed
-
-Use MultiEdit to make all changes in a single operation.
-Preserve exact indentation and formatting.
-```
-
-This is ideal as an agent step because:
-- Specific line numbers and method names
-- Exact refactoring instructions
-- No room for interpretation
-
-### Example 3: Test Generation
-
-**Regular Step (plan_test_coverage/prompt.md):**
-```markdown
-Analyze the {{file}} and determine what test cases would provide comprehensive coverage. Consider:
-- Happy path scenarios
-- Edge cases
-- Error conditions
-- Boundary values
-
-Focus on behavior, not implementation details.
-```
-
-**Agent Step (^implement_tests/prompt.md):**
-```markdown
-Create test file: test/models/user_validator_test.rb
-
-Implement exactly these test cases:
-1. test "validates email format"
-   - Use valid emails: ["user@example.com", "test.user+tag@domain.co.uk"]
-   - Use invalid emails: ["invalid", "@example.com", "user@", "user space@example.com"]
-   
-2. test "validates age is positive integer"
-   - Valid: [18, 25, 100]
-   - Invalid: [-1, 0, 17, 101, "twenty", nil]
-
-3. test "validates username uniqueness"
-   - Create user with username "testuser"
-   - Attempt to create second user with same username
-   - Assert validation error on :username
-
-Use minitest assertion style.
-Each test must be independent.
-Use setup method for common test data.
-```
-
-### Example 4: API Integration
-
-**Regular Step (design_api_client/prompt.md):**
-```markdown
-Design a client for the {{api_name}} API that follows Ruby best practices. Consider:
-- Error handling strategies
-- Rate limiting
-- Authentication patterns
-- Response parsing
-- Testing approach
-
-Suggest an architecture that will be maintainable and extensible.
-```
-
-**Agent Step (^implement_api_client/prompt.md):**
-```markdown
-Implement the API client with this exact structure:
-
-1. Create file: lib/external_apis/weather_api/client.rb
-   ```ruby
-   module ExternalApis
-     module WeatherApi
-       class Client
-         include HTTParty
-         base_uri 'https://api.weather.com/v1'
-         
-         def initialize(api_key)
-           @api_key = api_key
-           @options = { headers: { 'Authorization' => "Bearer #{api_key}" } }
-         end
-         
-         def current_weather(location)
-           response = self.class.get("/current", @options.merge(query: { location: location }))
-           handle_response(response)
-         end
-         
-         private
-         
-         def handle_response(response)
-           raise ApiError, response.message unless response.success?
-           response.parsed_response
-         end
-       end
-     end
-   end
-   ```
-
-2. Create file: lib/external_apis/weather_api/api_error.rb
-   Define custom exception class
-
-3. Update file: config/initializers/weather_api.rb
-   Add configuration for API endpoint and timeout
-
-Use exact module structure and method signatures shown.
-```
-
-## Best Practices
-
-1. **Be explicit about tool usage in agent steps**
-   ```markdown
-   # Good agent step
-   Use MultiEdit tool to update the following files:
-   - app/models/user.rb: Add validation
-   - test/models/user_test.rb: Add test case
-   ```
-
-2. **Include specific line numbers or code markers when possible**
-   ```markdown
-   # Good agent step
-   In app/controllers/application_controller.rb:
-   - Find method `authenticate_user!` (around line 45)
-   - Add the following before the redirect_to call:
-     session[:return_to] = request.fullpath
-   ```
-
-3. **Specify exact formatting requirements**
-   ```markdown
-   # Good agent step
-   Create method with exactly this signature:
-   def calculate_tax(amount, rate = 0.08)
-   
-   Ensure:
-   - Two-space indentation
-   - No trailing whitespace
-   - Blank line before method definition
-   ```
-
-4. **Chain agent steps for complex operations**
-   ```yaml
-   steps:
-     # First understand the system
-     - analyze_current_architecture
-     
-     # Then execute precise changes
-     - ^create_service_objects
-     - ^update_controllers  
-     - ^add_test_coverage
-     
-     # Finally verify
-     - verify_all_tests_pass
-   ```
-
-## Summary
-
-Agent steps are powerful when you need direct control over tool usage and precise execution of technical tasks. They complement regular steps by handling the implementation details while regular steps handle the analysis and planning.
-
-The `continue` and `include_context_summary` options make agent steps even more powerful for iterative development workflows where maintaining context is important.
-
-Choose agent steps when precision matters more than interpretation. Choose regular steps when context and judgment are important.