roast-ai 0.4.9 → 0.5.0

data/lib/roast/dsl/cogs/chat.rb

@@ -0,0 +1,81 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      # Chat cog for pure LLM interaction
+      #
+      # The chat cog provides pure LLM interaction without local system access. While it
+      # cannot access local files or run local tools, it can still perform complex reasoning and
+      # access any cloud-based tools and MCP servers according to the capabilities of the model and
+      # the capabilities that may be provided to it by the LLM provider.
+      #
+      # Key characteristics:
+      # - No access to local filesystem (cannot read or write local files)
+      # - Cannot run local tools or commands
+      # - Can access cloud-based tools and MCP servers provided by the LLM provider
+      # - Performs request-response interactions
+      # - Does not currently maintain conversation state across invocations (not yet implemented)
+      # - Does not currently support automatic session resumption (not yet implemented)
+      #
+      # For tasks requiring local filesystem access or locally-configured tools, use the `agent` cog instead.
+      class Chat < Cog
+        # The configuration object for this chat cog instance
+        #
+        #: Roast::DSL::Cogs::Chat::Config
+        attr_reader :config
+
+        # Execute the chat completion with the given input and return the output
+        #
+        #: (Input) -> Output
+        def execute(input)
+          chat = ruby_llm_context.chat(
+            model: config.valid_model,
+            provider: config.valid_provider!,
+            assume_model_exists: !config.verify_model_exists?,
+          )
+          input.valid_session&.apply!(chat)
+          chat = chat.with_temperature(config.valid_temperature) if config.valid_temperature
+          num_existing_messages = chat.messages.length
+
+          response = chat.ask(input.valid_prompt!)
+          chat.messages[num_existing_messages..].each do |message|
+            case message.role
+            when :user
+              puts "[USER PROMPT] #{message.content}" if config.show_prompt?
+            when :assistant
+              puts "[LLM RESPONSE] #{message.content}" if config.show_response?
+            else
+              # No other message types are expected, but let's show them if they do appear
+              # but only the user has requested some form of output
+              puts "[UNKNOWN] #{message.content}" if config.show_prompt? || config.show_response?
+            end
+          end
+          if config.show_stats?
+            temperature = chat.instance_variable_get(:@temperature)
+            puts "[LLM STATS]"
+            puts "\tModel: #{response.model_id}"
+            puts "\tTemperature: #{format("%0.2f", temperature)}" if temperature
+            puts "\tInput Tokens: #{response.input_tokens}"
+            puts "\tOutput Tokens: #{response.output_tokens}"
+          end
+
+          Output.new(Session.from_chat(chat), response.content)
+        end
+
+        private
+
+        # Get a RubyLLM context configured for this chat cog
+        #
+        #: () -> RubyLLM::Context
+        def ruby_llm_context
+          @ruby_llm_context ||= RubyLLM.context do |context|
+            context.openai_api_key = config.valid_api_key!
+            context.openai_api_base = config.valid_base_url
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/cogs/cmd.rb

@@ -5,49 +5,313 @@ module Roast
   module DSL
     module Cogs
       class Cmd < Cog
-        class Output
-          #: String?
-          attr_reader :command_output
+        # Configure the `cmd` cog
+        #
+        # See sorbet/rbi/shims/lib/roast/dsl/config_context.rbi for full class documentation.
+        class Config < Cog::Config
+          # Configure the cog to consider itself failed if the command returns a non-zero exit status
+          #
+          # Enabled by default. When enabled, a non-zero exit status will mark the cog as failed,
+          # which may also abort the workflow depending on the cog's `abort_on_failure` configuration.
+          #
+          # #### Inverse Methods
+          # - `no_fail_on_error!`
+          #
+          # #### See Also
+          # - `fail_on_error?`
+          # - `abort_on_failure!`
+          #
+          #: () -> void
+          def fail_on_error!
+            @values[:fail_on_error] = true
+          end
 
-          #: String?
-          attr_reader :err
+          # Configure the cog __not__ to consider itself failed if the command returns a non-zero exit status
+          #
+          # When disabled, the cog will complete successfully regardless of the command's exit status.
+          # The exit status will still be available in the output for inspection.
+          #
+          # #### Inverse Methods
+          # - `fail_on_error!`
+          #
+          # #### See Also
+          # - `fail_on_error?`
+          #
+          #: () -> void
+          def no_fail_on_error!
+            @values[:fail_on_error] = false
+          end
 
-          #: Process::Status?
-          attr_reader :status
+          # Check if the cog is configured to fail when the command returns a non-zero exit status
+          #
+          # #### See Also
+          # - `fail_on_error!`
+          # - `no_fail_on_error!`
+          #
+          #: () -> bool
+          def fail_on_error?
+            @values[:fail_on_error] != false
+          end
+
+          # Configure the cog to write STDOUT to the console
+          #
+          # Disabled by default.
+          #
+          # #### See Also
+          # - `no_show_stdout!`
+          # - `show_stdout?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_stdout!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
 
-          #: (
-          #|  String? output,
-          #|  String? error,
-          #|  Process::Status? status
-          #| ) -> void
-          def initialize(output, error, status)
-            @command_output = output
-            @err = error
-            @status = status
+            @values[:show_stdout] = true
           end
-        end
 
-        class Config < Cog::Config
+          # Configure the cog __not__ to write STDOUT to the console
+          #
+          # #### See Also
+          # - `show_stdout!`
+          # - `show_stdout?`
+          # - `no_display!`
+          #
           #: () -> void
-          def print_all!
-            @values[:print_all] = true
+          def no_show_stdout!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = false
           end
 
+          # Check if the cog is configured to write STDOUT to the console
+          #
+          # #### See Also
+          # - `show_stdout!`
+          # - `no_show_stdout!`
+          #
           #: () -> bool
-          def print_all?
-            !!@values[:print_all]
+          def show_stdout?
+            !!@values[:show_stdout]
           end
 
+          # Configure the cog to write STDERR to the console
+          #
+          # Disabled by default.
+          #
+          # #### See Also
+          # - `no_show_stderr!`
+          # - `show_stderr?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_stderr!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stderr] = true
+          end
+
+          # Configure the cog __not__ to write STDERR to the console
+          #
+          # #### See Also
+          # - `show_stderr!`
+          # - `show_stderr?`
+          # - `no_display!`
+          #
+          #: () -> void
+          def no_show_stderr!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stderr] = false
+          end
+
+          # Check if the cog is configured to write STDERR to the console
+          #
+          # #### See Also
+          # - `show_stderr!`
+          # - `no_show_stderr!`
+          #
+          #: () -> bool
+          def show_stderr?
+            !!@values[:show_stderr]
+          end
+
+          # Configure the cog to write both STDOUT and STDERR to the console
+          #
+          # #### Alias Methods
+          # - `display!`
+          # - `print_all!`
+          #
+          # #### See Also
+          # - `no_display!`
+          # - `show_stdout!`
+          # - `show_stderr!`
+          #
+          #: () -> void
           def display!
-            print_all!
+            raise "⚠️ DEPRECATION: use display! instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = true
+            @values[:show_stderr] = true
+          end
+
+          # Configure the cog to write __no output__ to the console, neither STDOUT nor STDERR
+          #
+          # #### Alias Methods
+          # - `no_display!`
+          # - `print_none!`
+          # - `quiet!`
+          #
+          # #### See Also
+          # - `display!`
+          # - `no_show_stdout!`
+          # - `no_show_stderr!`
+          #
+          #: () -> void
+          def no_display!
+            raise "⚠️ DEPRECATION: use no_display! instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = false
+            @values[:show_stderr] = false
           end
+
+          # Check if the cog is configured to display any output while running
+          #
+          # #### See Also
+          # - `display!`
+          # - `no_display!`
+          # - `show_stdout?`
+          # - `show_stderr?`
+          #
+          #: () -> bool
+          def display?
+            show_stdout? || show_stderr?
+          end
+
+          alias_method(:quiet!, :no_display!)
+          alias_method(:print_all!, :display!)
+          alias_method(:print_none!, :no_display!)
+          alias_method(:print_stdout!, :show_stdout!)
+          alias_method(:no_print_stdout!, :no_show_stdout!)
+          alias_method(:print_stderr!, :show_stderr!)
+          alias_method(:no_print_stderr!, :no_show_stderr!)
         end
 
-        #: (String) -> Output
+        # Input specification for the cmd cog
+        #
+        # The cmd cog requires a command to execute, optionally with arguments.
+        # The command will be executed in the configured working directory.
+        class Input < Cog::Input
+          # The command to execute
+          #
+          #: String?
+          attr_accessor :command
+
+          # Arguments to pass to the command
+          #
+          #: Array[String]
+          attr_accessor :args
+
+          # Data to pass to command's standard input
+          #
+          #: String?
+          attr_accessor :stdin
+
+          #: () -> void
+          def initialize
+            super
+            @args = []
+          end
+
+          # Validate that the input has all required parameters
+          #
+          # This method ensures that a command has been provided before the cmd cog executes.
+          #
+          # #### See Also
+          # - `coerce`
+          #
+          #: () -> void
+          def validate!
+            raise Cog::Input::InvalidInputError, "'command' is required" unless command.present?
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # If the input block returns a String, it will be used as the command value.
+          # If the input block returns an Array, the first element will be used as the command
+          # and the remaining elements will be used as arguments.
+          #
+          # #### See Also
+          # - `validate!`
+          #
+          #: (String | Array[untyped]) -> void
+          def coerce(input_return_value)
+            case input_return_value
+            when String
+              self.command = input_return_value
+            when Array
+              input_return_value.map!(&:to_s)
+              self.command = input_return_value.shift
+              self.args = input_return_value
+            end
+          end
+        end
+
+        # Output from running the cmd cog
+        #
+        # Contains the standard output, standard error, and exit status from the executed command.
+        # Includes JSON and text parsing capabilities via `WithJson` and `WithText` modules.
+        class Output < Cog::Output
+          include Cog::Output::WithJson
+          include Cog::Output::WithNumber
+          include Cog::Output::WithText
+
+          # The standard output (STDOUT) from the command
+          #
+          #: String
+          attr_reader :out
+
+          # The standard error (STDERR) from the command
+          #
+          #: String
+          attr_reader :err
+
+          # The exit status of the command process
+          #
+          #: Process::Status
+          attr_reader :status
+
+          #: ( String, String, Process::Status) -> void
+          def initialize(out, err, status)
+            super()
+            @out = out #: String
+            @err = err #: String
+            @status = status #: Process::Status
+          end
+
+          private
+
+          def raw_text
+            out
+          end
+        end
+
+        #: (Input) -> Output
         def execute(input)
-          result = Output.new(*Roast::Helpers::CmdRunner.capture3(input))
-          puts result.command_output if @config.print_all?
-          result
+          config = @config #: as Config
+
+          stdout_handler = config.show_stdout? ? ->(line) { $stdout.print(line) } : nil
+          stderr_handler = config.show_stderr? ? ->(line) { $stderr.print(line) } : nil
+
+          stdout, stderr, status = CommandRunner #: as untyped
+            .execute(
+              [input.command] + input.args,
+              working_directory: config.valid_working_directory,
+              stdin_content: input.stdin,
+              stdout_handler: stdout_handler,
+              stderr_handler: stderr_handler,
+            )
+
+          Output.new(stdout, stderr, status)
         end
       end
     end

data/lib/roast/dsl/cogs/ruby.rb

@@ -0,0 +1,171 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Ruby < Cog
+        class Config < Cog::Config; end
+
+        # Input specification for the ruby cog
+        #
+        # The ruby cog accepts any Ruby value from the input block, which will be directly
+        # passed through to the output without modification.
+        class Input < Cog::Input
+          # The value to pass through to the output
+          #
+          # This value will be directly returned as the `value` attribute on the cog's output object.
+          #
+          #: untyped
+          attr_accessor :value
+
+          # Validate that the input has all required parameters
+          #
+          # This method ensures that a value has been provided, either directly via the `value`
+          # attribute or through the input block (via `coerce`).
+          #
+          # #### See Also
+          # - `coerce`
+          #
+          #: () -> void
+          def validate!
+            raise Cog::Input::InvalidInputError if value.nil? && !coerce_ran?
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # The return value from the input block will be used directly as the `value` attribute.
+          # This allows any Ruby object to be passed through the ruby cog.
+          #
+          # #### See Also
+          # - `validate!`
+          #
+          #: (untyped) -> void
+          def coerce(input_return_value)
+            super
+            @value = input_return_value
+          end
+        end
+
+        # Output from running the ruby cog
+        #
+        # Contains the value that was provided to the input block, passed through unchanged.
+        # This allows Ruby values to be used directly in workflow steps.
+        #
+        # The output provides convenient dynamic method dispatch with the following priority:
+        # 1. If the value object responds to a method, it delegates to that method
+        # 2. If the value is a Hash, methods correspond to hash keys
+        # 3. Hash values that are Procs can be called directly as methods
+        #
+        # Additional conveniences:
+        # - Use `[]` for direct hash key access when the value is a Hash
+        # - Use `call()` to invoke the value if it's a Proc, or to call a Proc stored in a Hash
+        class Output < Cog::Output
+          # The value passed through from the input
+          #
+          #: untyped
+          attr_reader :value
+
+          #: (untyped) -> void
+          def initialize(value)
+            super()
+            @value = value
+          end
+
+          # Access a hash key directly when the value is a Hash
+          #
+          # Provides direct bracket notation access to hash keys without going through
+          # method dispatch. This is useful when you need explicit hash key access.
+          #
+          # #### See Also
+          # - `call`
+          # - `method_missing`
+          #
+          #: (Symbol) -> untyped
+          def [](key)
+            value[key]
+          end
+
+          # Call the value as a Proc, or call a Proc stored in a Hash
+          #
+          # This method provides two calling patterns:
+          # - If the value is a Proc, calls it directly with the provided arguments
+          # - If the value is a Hash, expects the first argument to be a Symbol key, retrieves
+          #   the Proc at that key, and calls it with the remaining arguments
+          #
+          # Raises `ArgumentError` if called on a Hash without a Symbol key.
+          # Raises `NoMethodError` if the Hash key doesn't contain a Proc.
+          #
+          # #### See Also
+          # - `[]`
+          # - `method_missing`
+          #
+          #: (*untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+          def call(*args, **kwargs, &blk)
+            return value.call(*args, **kwargs, &blk) if value.is_a?(Proc)
+
+            key = args.first
+            raise ArgumentError unless key.is_a?(Symbol)
+
+            proc = value[key]
+            raise NoMethodError, key unless proc.is_a?(Proc)
+
+            proc = proc #: as untyped
+            proc.call(*args, **kwargs, &blk)
+          end
+
+          # Handle dynamic method calls with intelligent dispatch
+          #
+          # This method implements a multi-level dispatch strategy:
+          #
+          # 1. **Value delegation**: If the value object responds to the method, delegates directly to it.
+          #    This allows calling methods like `lines`, `length`, `upcase` on String values, or any
+          #    method on the underlying object.
+          #
+          # 2. **Hash key access**: If the value is a Hash and contains the method name as a key,
+          #    returns the value at that key. If the value is a Proc, calls it with the provided arguments.
+          #
+          # 3. **Fallback**: If neither condition is met, calls `super` to trigger standard Ruby behavior.
+          #
+          # #### See Also
+          # - `respond_to_missing?`
+          # - `[]`
+          # - `call`
+          #
+          #: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+          def method_missing(name, *args, **kwargs, &blk)
+            return value.public_send(name, *args, **kwargs, &blk) if value.respond_to?(name, false)
+            return super unless value.is_a?(Hash) && value.key?(name)
+
+            if value[name].is_a?(Proc)
+              proc = value[name] #: as untyped
+              proc.call(*args, **kwargs, &blk)
+            else
+              value[name]
+            end
+          end
+
+          # Check if a dynamic method should respond
+          #
+          # Returns `true` if any of the following conditions are met:
+          # 1. The value object responds to the method
+          # 2. The value is a Hash and contains the method name as a key
+          # 3. The parent class would respond to the method
+          #
+          # #### See Also
+          # - `method_missing`
+          #
+          #: (Symbol | String, ?bool) -> bool
+          def respond_to_missing?(name, include_private = false)
+            value.respond_to?(name, false) || value.is_a?(Hash) && value.key?(name) || super
+          end
+        end
+
+        #: (Input) -> Output
+        def execute(input)
+          Output.new(input.value)
+        end
+      end
+    end
+  end
+end