roast-ai 0.4.9 → 0.5.0

data/lib/roast/dsl/cog/config.rb

@@ -1,30 +1,306 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 module Roast
   module DSL
     class Cog
+      # Base configuration class for all cogs
+      #
+      # Provides common configuration methods and utilities for cog behavior.
+      # Cogs extend this class to define their own configuration options using either
+      # the `field` class method for simple fields or custom methods for complex configuration.
       class Config
+        # Parent class for all configuration-related errors
+        class ConfigError < Roast::Error; end
+
+        # Raised when a configuration value is invalid or missing
+        class InvalidConfigError < ConfigError; end
+
+        # Validate that the config instance has all required parameters set in an acceptable manner
+        #
+        # Inheriting cogs should implement this method for their config class if validation is desired.
+        # This method is called after configuration is complete to ensure all required values are present
+        # and valid.
+        #
+        #: () -> void
+        def validate!; end
+
+        # The internal hash storing all configuration values
+        #
+        #: Hash[Symbol, untyped]
         attr_reader :values
 
+        #: (?Hash[Symbol, untyped]) -> void
         def initialize(initial = {})
           @values = initial
         end
 
+        # Merge another config object into this one, returning a new config instance
+        #
+        # Creates a new config object with values from both this config and the provided config.
+        # Values from the provided config take precedence over values from this config.
+        #
+        # #### See Also
+        # - `values`
+        #
+        #: (Cog::Config) -> Cog::Config
         def merge(config_object)
           self.class.new(values.merge(config_object.values))
         end
 
-        # It is recommended to implement a custom config object for a nicer interface,
-        # but for simple cases where it would just be a key value store we provide one by default.
-
+        # Set a configuration value using hash-style syntax
+        #
+        # This method provides basic key-value storage for cog configuration.
+        # All standard Roast cogs use imperative setter methods for config values.
+        # It is recommended that custom cogs implement their own config classes with similar methods
+        # for a more structured interface, but this hash-style syntax is provided for simple cases.
+        #
+        # #### See Also
+        # - `[]`
+        #
+        #: (Symbol, untyped) -> void
         def []=(key, value)
           @values[key] = value
         end
 
+        # Get a configuration value using hash-style syntax
+        #
+        # This method provides basic key-value retrieval for cog configuration.
+        # All standard Roast cogs use imperative setter methods for config values.
+        # It is recommended that custom cogs implement their own config classes with similar methods
+        # for a more structured interface, but this hash-style syntax is provided for simple cases.
+        #
+        # #### See Also
+        # - `[]=`
+        #
+        #: (Symbol) -> untyped
         def [](key)
           @values[key]
         end
+
+        class << self
+          # Define a configuration field with simple, out-of-the-box getter/setter behavior
+          # and default value handling
+          #
+          # #### Generated Methods
+          # This method creates two methods for a configuration field:
+          # 1. A dual-purpose method (`key`) that gets the value when called without arguments,
+          #    or sets the value when called with an argument.
+          # 2. A bang method (`use_default_#{key}!`) that explicitly resets the field to its default value.
+          #
+          # When getting a value without arguments, the configured value is returned if set,
+          # otherwise the default value is returned.
+          # When setting a value with an argument, the validator block is applied if provided.
+          #
+          # #### Validation
+          #
+          # This method accepts an optional `validator` block that will be called with the new value
+          # when the field's setter method is invoked. The validator should raise an exception if the
+          # provided value is not valid. It's return value will be used as the new config value.
+          # This allows the validator to coerce an value into a standard form if desired.
+          #
+          # ##### See Also
+          # - `Cog::Config#validate!` - validates the config object as a whole, after all values have been set
+          #
+          # #### Parameters
+          # - `key` - The name of the configuration field
+          # - `default` - The default value for this field
+          # - `validator` - Optional block that validates and/or transforms the value before storing it
+          #
+          #: [T] (Symbol, T) ?{(T) -> T} -> void
+          def field(key, default, &validator)
+            default = default #: as untyped
+
+            define_method(key) do |*args|
+              if args.empty?
+                # with no args, return the configured value, or the default
+                @values[key] || default.deep_dup
+              else
+                # with an argument, set the configured value
+                new_value = args.first
+                @values[key] = validator ? validator.call(new_value) : new_value
+              end
+            end
+
+            define_method("use_default_#{key}!".to_sym) do
+              # explicitly set the configured value to the default
+              @values[key] = default.deep_dup
+            end
+          end
+        end
+
+        # Configure the cog to run asynchronously in the background
+        #
+        # When configured to run asynchronously, the cog will execute in the background
+        # and the next cog in the workflow will be able to start immediately without waiting
+        # for this cog to complete.
+        #
+        # If this cog has started running, attempts to access its output from another cog will
+        # block until this cog completes.
+        # If this cog has not yet started, attempts to access its output from another cog will
+        # fail in the same way that accessing the output of a synchronous cog that has not yet
+        # run would fail.
+        #
+        # The workflow will not complete until all asynchronous cogs have completed (or failed).
+        #
+        # #### Inverse Methods
+        # - `no_async!`
+        # - `sync!`
+        #
+        # #### See Also
+        # - `async?`
+        #
+        #: () -> void
+        def async!
+          @values[:async] = true
+        end
+
+        # Configure the cog __not__ to run asynchronously
+        #
+        # When configured not to run asynchronously, the cog will execute synchronously
+        # and the next cog in the workflow will wait for this cog to complete before starting.
+        #
+        # #### Alias Methods
+        # - `no_async!`
+        # - `sync!`
+        #
+        # #### Inverse Methods
+        # - `async!`
+        #
+        # #### See Also
+        # - `async?`
+        #
+        #: () -> void
+        def no_async!
+          @values[:async] = false
+        end
+
+        # Check if the cog is configured to run asynchronously
+        #
+        # #### See Also
+        # - `async!`
+        # - `no_async!`
+        # - `sync!`
+        #
+        #: () -> bool
+        def async?
+          !!@values[:async]
+        end
+
+        # Configure the cog to abort the workflow immediately if it fails to complete successfully
+        #
+        # Enabled by default.
+        #
+        # #### Inverse Methods
+        # - `continue_on_failure!`
+        # - `no_abort_on_failure!`
+        #
+        # #### See Also
+        # - `abort_on_failure?`
+        #
+        #: () -> void
+        def abort_on_failure!
+          @values[:abort_on_failure] = true
+        end
+
+        # Configure the cog __not__ to abort the workflow if it fails to complete successfully
+        #
+        # When a cog is configured not to abort on failure, the workflow will continue to run subsequent cogs
+        # even if a cog fails. However, attempts to access that cog's output from another cog will fail.
+        #
+        # #### Alias Methods
+        # - `continue_on_failure!`
+        #
+        # #### Inverse Methods
+        # - `abort_on_failure!`
+        #
+        # #### See Also
+        # - `abort_on_failure?`
+        #
+        #: () -> void
+        def no_abort_on_failure!
+          @values[:abort_on_failure] = false
+        end
+
+        # Check if the cog is configured to abort the workflow immediately on failure
+        #
+        # #### See Also
+        # - `abort_on_failure!`
+        # - `continue_on_failure!`
+        # - `no_abort_on_failure!`
+        #
+        #: () -> bool
+        def abort_on_failure?
+          @values[:abort_on_failure] ||= true
+        end
+
+        # Configure the cog to run external commands in the specified working directory
+        #
+        # The directory given can be relative or absolute.
+        # If relative, it will be understood in relation to the directory from which Roast is invoked.
+        #
+        # ---
+        #
+        # __Important Note__: this configuration option only applies to external commands invoked by a cog
+        # It does not affect the working directory in which Roast is running.
+        #
+        # ---
+        #
+        # #### See Also
+        # - `use_current_working_directory!`
+        # - `valid_working_directory`
+        #
+        #: (String) -> void
+        def working_directory(directory)
+          @values[:working_directory] = directory
+        end
+
+        # Configure the cog to run in the directory from which Roast is invoked
+        #
+        # ---
+        #
+        # __Important Note__: this configuration option only applies to external commands invoked by a cog
+        # It does not affect the working directory in which Roast is running.
+        #
+        # ---
+        #
+        # #### See Also
+        # - `working_directory`
+        # - `valid_working_directory`
+        #
+        #: () -> void
+        def use_current_working_directory!
+          @values[:working_directory] = nil
+        end
+
+        # Get the validated, configured value for the working directory path in which the cog should run
+        #
+        # A value of `nil` means to use the current working directory.
+        # This method will raise an `InvalidConfigError` if the path does not exist or is not a directory.
+        #
+        # ---
+        #
+        # __Important Note__: this configuration option only applies to external commands invoked by a cog
+        # It does not affect the working directory in which Roast is running.
+        #
+        # ---
+        #
+        # #### See Also
+        # - `working_directory`
+        # - `use_current_working_directory!`
+        #
+        #: () -> Pathname?
+        def valid_working_directory
+          path = Pathname.new(@values[:working_directory]).expand_path if @values[:working_directory]
+          return unless path
+          raise InvalidConfigError, "working directory '#{path}' does not exist'" unless path.exist?
+          raise InvalidConfigError, "working directory '#{path}' is not a directory'" unless path.directory?
+
+          path
+        end
+
+        alias_method(:continue_on_failure!, :no_abort_on_failure!)
+        alias_method(:sync!, :no_async!)
       end
     end
   end

data/lib/roast/dsl/cog/input.rb

@@ -0,0 +1,73 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    class Cog
+      # Abstract parent class for inputs provided to a cog when it runs
+      #
+      # Cogs extend this class to define their own input types that specify what data the cog needs to execute.
+      # Input classes must be instantiatable with a no-argument constructor and expose methods to incrementally
+      # set their values.
+      #
+      # The input lifecycle:
+      # 1. An input instance is created when the cog is invoked
+      # 2. The `validate!` method is called to see if all required parameters are set correctly (errors are swallowed)
+      # 3. If validation fails, the `coerce` method is called with the return value from the input block (if provided)
+      # 4. The `validate!` method is called again to ensure all required parameters are set correctly (errors are raised)
+      # 4. The validated input is passed to the cog's `execute` method
+      class Input
+        # Parent class for all errors raised by the Roast::DSL::Input class
+        class InputError < Roast::Error; end
+
+        # Raised when validation fails on a cog's input object.
+        class InvalidInputError < InputError; end
+
+        # Validate that the input instance has all required parameters set in an acceptable manner
+        #
+        # Subclasses must implement this method to verify that the input is in a valid state before
+        # the cog executes. This method should raise an `InvalidInputError` if the input is not valid.
+        #
+        # #### See Also
+        # - `coerce`
+        #
+        #: () -> void
+        def validate!
+          raise NotImplementedError
+        end
+
+        # Use the value returned from the cog's input block to coerce the input to a valid state
+        #
+        # Subclasses may implement this method to automatically configure the input based on the return
+        # value from the input block. This is optional; if not implemented, the default behavior is to
+        # do nothing.
+        #
+        # #### See Also
+        # - `validate!`
+        #
+        #: (untyped) -> void
+        def coerce(input_return_value)
+          @coerce_ran = true
+        end
+
+        private
+
+        # Determine whether the input's coerce method has already been attempted
+        #
+        # This can be useful for validate! to adapt its behaviour based on whether it is being called the first
+        # or second time.
+        #
+        # For instance, if an input has an attribute than can legitimately be `nil`, but the cog
+        # still wants to attempt coercion if the attribute is not set to a non-`nil` value initially, `validate!`
+        # can be implemented to raise `InvalidInputError` if the attribute is `nil` and `coerce_ran?` is `false`,
+        # but not to raise if `coerce_ran?` is `true`, to allow the input to be ultimately validated with a `nil`
+        # value for that attribute.
+        #
+        #: () -> bool
+        def coerce_ran?
+          @coerce_ran ||= false
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/cog/output.rb

@@ -0,0 +1,313 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    class Cog
+      # Generic output from running a cog.
+      # Cogs should extend this class with their own output types.
+      class Output
+        # @requires_ancestor: Roast::DSL::Cog::Output
+        module WithJson
+          # Get parsed JSON from the output, raising an error if parsing fails
+          #
+          # This method attempts to parse JSON from the output text using multiple fallback strategies,
+          # including extracting from code blocks and JSON-like patterns. If the input is nil or empty,
+          # an empty hash is returned.
+          #
+          # #### See Also
+          # - `json`
+          #
+          #: () -> Hash[Symbol, untyped]
+          def json!
+            input = raw_text
+            return {} if input.nil? || input.strip.empty?
+
+            @json ||= parse_json_with_fallbacks(input)
+          end
+
+          # Get parsed JSON from the output, returning nil if parsing fails
+          #
+          # This method provides a safe alternative to `json!` that returns `nil` instead of raising
+          # an error when JSON parsing fails.
+          #
+          # #### See Also
+          # - `json!`
+          #
+          #: () -> Hash[Symbol, untyped]?
+          def json
+            json!
+          rescue JSON::ParserError
+            nil
+          end
+
+          private
+
+          # Cogs should implement this method to provide the text value that should be parsed to provide the 'json' attribute
+          #
+          #: () -> String?
+          def raw_text
+            raise NotImplementedError
+          end
+
+          # Try parsing JSON from various possible formats in priority order
+          #
+          #: (String) -> Hash[Symbol, untyped]
+          def parse_json_with_fallbacks(input)
+            candidates = extract_json_candidates(input)
+            candidates.each do |candidate|
+              return JSON.parse(candidate.strip, symbolize_names: true)
+            rescue JSON::ParserError, TypeError
+              nil
+            end
+            raise JSON::ParserError, "Could not parse JSON from input:\n---\n#{input}\n---"
+          end
+
+          # Extract potential JSON strings in priority order
+          #
+          #: (String) -> Array[String]
+          def extract_json_candidates(input)
+            [
+              input.strip, # 1. Entire input
+              *extract_code_blocks(input, "json").reverse,    # 2. ```json blocks (last first)
+              *extract_code_blocks(input, nil).reverse,       # 3. ``` blocks (last first)
+              *extract_code_blocks(input, :any).reverse,      # 4. ```type blocks (last first)
+              *extract_json_like_blocks(input), # 5. { } or [ ] blocks (longest first)
+            ].compact.uniq
+          end
+
+          # Extract code blocks with optional language specifier
+          # language can be: String (exact match), nil (no language), :any (any language except json/nil)
+          #
+          #: (String, String | Symbol | nil) -> Array[String]
+          def extract_code_blocks(input, language)
+            blocks = []
+            parts = input.split("```")
+
+            # Process pairs of splits (opening ``` and closing ```)
+            (1...parts.length).step(2) do |i|
+              block_with_header = parts[i]
+              next unless block_with_header
+
+              lines = block_with_header.lines
+              first_line = lines.first&.strip || ""
+              content = (lines[1..] || []).join
+
+              case language
+              when String
+                blocks << content if first_line == language
+              when nil
+                blocks << content if first_line.empty?
+              when :any
+                blocks << content if !first_line.empty? && first_line != "json"
+              end
+            end
+
+            blocks
+          rescue
+            []
+          end
+
+          # Extract blocks that look like JSON objects or arrays
+          #
+          #: (String) -> Array[String]
+          def extract_json_like_blocks(input)
+            blocks = []
+
+            # Find all potential JSON blocks starting with { or [ and ending with } or ]
+            input.scan(/^[ \t]*([{\[].*?[}\]])[ \t]*$/m) do |match|
+              blocks << match[0]
+            end
+
+            # Also try to find JSON anywhere in the text (not just at line boundaries)
+            input.scan(/([{\[](?:[^{}\[\]]|(?:\{(?:[^{}]|\{[^{}]*\})*\})|(?:\[(?:[^\[\]]|\[[^\[\]]*\])*\]))*[}\]])/m) do |match|
+              blocks << match[0]
+            end
+
+            # Sort by length (longest first) and deduplicate
+            blocks.uniq.sort_by { |b| -b.length }
+          end
+        rescue
+          []
+        end
+
+        # @requires_ancestor: Roast::DSL::Cog::Output
+        module WithNumber
+          # Get parsed float from the output, raising an error if parsing fails
+          #
+          # This method attempts to parse a float from the output text using multiple permissive fallback
+          # strategies to extract a substring that looks like a number.
+          #
+          # Raises `ArgumentError` if output text does not contain any value that can be parsed as a number.
+          #
+          # #### See Also
+          # - `float`
+          # - `integer!`
+          # - `integer`
+          #
+          #: () -> Float
+          def float!
+            @float ||= parse_number_with_fallbacks(raw_text || "")
+          end
+
+          # Get parsed float from the output, returning nil if parsing fails
+          #
+          # This method attempts to parse a float from the output text using multiple permissive fallback
+          # strategies to extract a substring that looks like a number.
+          #
+          # Returns `nil` if output text does not contain any value that can be parsed as a number.
+          #
+          # #### See Also
+          # - `float!`
+          # - `integer!`
+          # - `integer`
+          #
+          #: () -> Float?
+          def float
+            float!
+          rescue ArgumentError
+            nil
+          end
+
+          # Get parsed integer from the output, raising an error if parsing fails
+          #
+          # This method attempts to parse an integer from the output text using multiple permissive fallback
+          # strategies to extract a substring that looks like a number. This method will attempt to parse
+          # and round a floating point value; it will not strictly match only integers in the source text.
+          #
+          # Raises `ArgumentError` if output text does not contain any value that can be parsed as a number.
+          #
+          # #### See Also
+          # - `integer`
+          # - `float!`
+          # - `float`
+          #
+          #: () -> Integer
+          def integer!
+            @integer ||= float!.round
+          end
+
+          # Get parsed integer from the output, returning nil if parsing fails
+          #
+          # This method attempts to parse an integer from the output text using multiple permissive fallback
+          # strategies to extract a substring that looks like a number. This method will attempt to parse
+          # and round a floating point value; it will not strictly match only integers in the source text.
+          #
+          # Returns `nil` if output text does not contain any value that can be parsed as a number.
+          #
+          # #### See Also
+          # - `integer!`
+          # - `float!`
+          # - `float`
+          #
+          #: () -> Integer?
+          def integer
+            integer!
+          rescue ArgumentError
+            nil
+          end
+
+          private
+
+          # Try parsing a number from various possible formats in priority order
+          #
+          #: (String) -> Float
+          def parse_number_with_fallbacks(input)
+            candidates = extract_number_candidates(input)
+            candidates.each do |candidate|
+              normalized = normalize_number_string(candidate)
+              next if normalized.nil?
+
+              return Float(normalized)
+            rescue ArgumentError, TypeError
+              next
+            end
+            raise ArgumentError, "Could not parse number from input:\n---\n#{input}\n---"
+          end
+
+          # Extract potential number strings in priority order
+          #
+          #: (String) -> Array[String]
+          def extract_number_candidates(input)
+            candidates = []
+
+            # 1. Try the entire string
+            candidates << input.strip
+
+            # 2. Try each line from bottom up (with whitespace stripped)
+            lines = input.lines.map(&:strip).reject(&:empty?)
+            candidates.concat(lines.reverse)
+
+            # 3. Try to extract numbers from each line from bottom up
+            lines.reverse.each do |line|
+              # Look for numbers with various separators, formats, and currency symbols (very permissive)
+              # Matches: 123, 1,234, 1_234, 1 234, 1.23, -1.23, 1.23e10, 1.23e-10
+              matches = line.scan(/-?[\d\s$¢£€¥.,_]+(?:[eE][+-]?\d+)?/) #: as Array[String]
+              candidates.concat(matches.map(&:strip))
+            end
+
+            candidates.compact.uniq
+          end
+
+          # Normalize a number string by removing separators and currency codes and validating format
+          #
+          #: (String) -> String?
+          def normalize_number_string(raw)
+            # Remove common digit separators and currency codes
+            normalized = raw.strip.gsub(/[\s$¢£€¥,_]/, "")
+
+            # Validate it looks like a number (optional minus, digits, optional decimal, optional scientific notation)
+            normalized if normalized.match?(/\A-?\d+(?:\.\d*)?(?:[eE][+-]?\d+)?\z/)
+          end
+        end
+
+        # @requires_ancestor: Roast::DSL::Cog::Output
+        module WithText
+          # Get the output as a single string with surrounding whitespace removed
+          #
+          # This method returns the text output with leading and trailing whitespace stripped.
+          #
+          # #### See Also
+          # - `lines`
+          #
+          #: () -> String
+          def text
+            raw_text.strip
+          end
+
+          # Get the output as an array of lines with each line's whitespace stripped
+          #
+          # This method splits the output into individual lines and removes leading and trailing
+          # whitespace from each line.
+          #
+          # #### See Also
+          # - `text`
+          #
+          #: () -> Array[String]
+          def lines
+            raw_text.lines.map(&:strip)
+          end
+
+          private
+
+          # Cogs should implement this method to provide the text value of their output
+          #
+          #: () -> String
+          def raw_text
+            raise NotImplementedError
+          end
+        end
+
+        private
+
+        # Cogs should implement this method to provide the text value that should be parsed to provide the
+        # the values produced by the `WithText`, `WithJson`, and `WithNumber` modules.
+        #
+        #: () -> String?
+        def raw_text
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end