flowengine 0.1.1 → 0.2.1

data/lib/flowengine/engine.rb

@@ -1,28 +1,46 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Runtime session that drives flow navigation: holds definition, answers, and current step.
+  # Validates each answer via an optional {Validation::Adapter}, then advances using node transitions.
+  #
+  # @attr_reader definition [Definition] immutable flow definition
+  # @attr_reader answers [Hash] step_id => value (mutable as user answers)
+  # @attr_reader history [Array<Symbol>] ordered list of step ids visited (including current)
+  # @attr_reader current_step_id [Symbol, nil] current step id, or nil when flow is finished
+  # @attr_reader introduction_text [String, nil] free-form text submitted before the flow began
   class Engine
-    attr_reader :definition, :answers, :history, :current_step_id
+    attr_reader :definition, :answers, :history, :current_step_id, :introduction_text
 
+    # @param definition [Definition] the flow to run
+    # @param validator [Validation::Adapter] validator for step answers (default: {Validation::NullAdapter})
     def initialize(definition, validator: Validation::NullAdapter.new)
       @definition = definition
       @answers = {}
       @history = []
       @current_step_id = definition.start_step_id
       @validator = validator
+      @introduction_text = nil
       @history << @current_step_id
     end
 
+    # @return [Node, nil] current step node, or nil if flow is finished
     def current_step
       return nil if finished?
 
       definition.step(@current_step_id)
     end
 
+    # @return [Boolean] true when there is no current step (flow ended)
     def finished?
       @current_step_id.nil?
     end
 
+    # Submits an answer for the current step, validates it, stores it, and advances to the next step.
+    #
+    # @param value [Object] user's answer for the current step
+    # @raise [AlreadyFinishedError] if the flow has already finished
+    # @raise [ValidationError] if the validator rejects the value
     def answer(value)
       raise AlreadyFinishedError, "Flow is already finished" if finished?
 
@@ -33,14 +51,41 @@ module FlowEngine
       advance_step
     end
 
+    # Submits free-form introduction text, filters sensitive data, calls the LLM
+    # to extract answers, and auto-advances through pre-filled steps.
+    #
+    # @param text [String] user's free-form introduction
+    # @param llm_client [LLM::Client] configured LLM client for parsing
+    # @raise [SensitiveDataError] if text contains SSN, ITIN, EIN, etc.
+    # @raise [ValidationError] if text exceeds the introduction maxlength
+    # @raise [LLMError] on LLM communication or parsing failures
+    def submit_introduction(text, llm_client:)
+      validate_introduction_length!(text)
+      LLM::SensitiveDataFilter.check!(text)
+      @introduction_text = text
+      extracted = llm_client.parse_introduction(definition: @definition, introduction_text: text)
+      @answers.merge!(extracted)
+      auto_advance_prefilled
+    end
+
+    # Serializable state for persistence or resumption.
+    #
+    # @return [Hash] current_step_id, answers, history, and introduction_text
     def to_state
       {
         current_step_id: @current_step_id,
         answers: @answers,
-        history: @history
+        history: @history,
+        introduction_text: @introduction_text
       }
     end
 
+    # Rebuilds an engine from a previously saved state (e.g. from DB or session).
+    #
+    # @param definition [Definition] same definition used when state was captured
+    # @param state_hash [Hash] hash with :current_step_id, :answers, :history (keys may be strings)
+    # @param validator [Validation::Adapter] validator to use (default: NullAdapter)
+    # @return [Engine] restored engine instance
     def self.from_state(definition, state_hash, validator: Validation::NullAdapter.new)
       state = symbolize_state(state_hash)
       engine = allocate
@@ -48,6 +93,10 @@ module FlowEngine
       engine
     end
 
+    # Normalizes a state hash so step ids and history entries are symbols; answers keys are symbols.
+    #
+    # @param hash [Hash] raw state (e.g. from JSON)
+    # @return [Hash] symbolized state
     def self.symbolize_state(hash)
       return hash unless hash.is_a?(Hash)
 
@@ -66,6 +115,8 @@ module FlowEngine
       end
     end
 
+    # @param answers [Hash] answers map (keys may be strings)
+    # @return [Hash] same map with symbol keys
     def self.symbolize_answers(answers)
       return {} unless answers.is_a?(Hash)
 
@@ -84,6 +135,7 @@ module FlowEngine
       @current_step_id = state[:current_step_id]
       @answers = state[:answers] || {}
       @history = state[:history] || []
+      @introduction_text = state[:introduction_text]
     end
 
     def advance_step
@@ -93,5 +145,19 @@ module FlowEngine
       @current_step_id = next_id
       @history << next_id if next_id
     end
+
+    def validate_introduction_length!(text)
+      maxlength = @definition.introduction&.maxlength
+      return unless maxlength
+      return if text.length <= maxlength
+
+      raise ValidationError, "Introduction text exceeds maxlength (#{text.length}/#{maxlength})"
+    end
+
+    # Advances through consecutive steps that already have pre-filled answers.
+    # Stops at the first step without a pre-filled answer or when the flow ends.
+    def auto_advance_prefilled
+      advance_step while @current_step_id && @answers.key?(@current_step_id)
+    end
   end
 end

data/lib/flowengine/errors.rb

@@ -1,10 +1,27 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Base exception for all flowengine errors.
   class Error < StandardError; end
+
+  # Raised when a flow definition is invalid (e.g. missing start step, unknown step reference).
   class DefinitionError < Error; end
+
+  # Raised when navigating to or requesting a step id that does not exist in the definition.
   class UnknownStepError < Error; end
+
+  # Base exception for runtime engine errors (e.g. validation, already finished).
   class EngineError < Error; end
+
+  # Raised when {Engine#answer} is called after the flow has already finished.
   class AlreadyFinishedError < EngineError; end
+
+  # Raised when the validator rejects the user's answer for the current step.
   class ValidationError < EngineError; end
+
+  # Raised for LLM-related errors (missing API key, response parsing, etc.).
+  class LLMError < Error; end
+
+  # Raised when introduction text contains sensitive data (SSN, ITIN, EIN, etc.).
+  class SensitiveDataError < EngineError; end
 end

data/lib/flowengine/evaluator.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Evaluates rule AST nodes against a given answer context.
+  # Used by transitions and visibility checks; rule objects implement {Rules::Base#evaluate}.
+  #
+  # @attr_reader answers [Hash] current answer state (step_id => value)
   class Evaluator
     attr_reader :answers
 
+    # @param answers [Hash] answer context to evaluate rules against
     def initialize(answers)
       @answers = answers
     end
 
+    # Evaluates a single rule (or returns true if rule is nil).
+    #
+    # @param rule [Rules::Base, nil] rule to evaluate
+    # @return [Boolean] result of rule#evaluate(answers), or true when rule is nil
     def evaluate(rule)
       return true if rule.nil?
 

data/lib/flowengine/graph/mermaid_exporter.rb

@@ -2,15 +2,22 @@
 
 module FlowEngine
   module Graph
+    # Exports a flow {Definition} to Mermaid flowchart syntax for visualization.
+    # Nodes are labeled with truncated question text; edges show condition labels when present.
     class MermaidExporter
+      # Maximum characters for node labels in the diagram (longer text is truncated with "...").
       MAX_LABEL_LENGTH = 50
 
       attr_reader :definition
 
+      # @param definition [Definition] flow to export
       def initialize(definition)
         @definition = definition
       end
 
+      # Generates Mermaid flowchart TD (top-down) source.
+      #
+      # @return [String] Mermaid diagram source (e.g. for Mermaid.js or docs)
       def export
         lines = ["flowchart TD"]
 

data/lib/flowengine/introduction.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  # Immutable introduction configuration for a flow. When present in a Definition,
+  # indicates the UI should collect free-form text before the first step.
+  # The label is shown above the input field; the placeholder appears inside it.
+  # maxlength limits the character count of the free-form text (nil = unlimited).
+  Introduction = Data.define(:label, :placeholder, :maxlength) do
+    def initialize(label:, placeholder: "", maxlength: nil)
+      super
+      freeze
+    end
+  end
+end

data/lib/flowengine/llm/adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Abstract adapter for LLM API calls. Subclass and implement {#chat}
+    # to integrate with a specific provider (OpenAI, Anthropic, etc.).
+    class Adapter
+      # Sends a system + user prompt pair to the LLM and returns the response text.
+      #
+      # @param system_prompt [String] system instructions for the LLM
+      # @param user_prompt [String] user's introduction text
+      # @param model [String] model identifier (e.g. "gpt-4o-mini")
+      # @return [String] the LLM's response text (expected to be JSON)
+      def chat(system_prompt:, user_prompt:, model:)
+        raise NotImplementedError, "#{self.class}#chat must be implemented"
+      end
+    end
+  end
+end

data/lib/flowengine/llm/client.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FlowEngine
+  module LLM
+    # High-level LLM client that parses introduction text into pre-filled answers.
+    # Wraps an {Adapter} and a model name, builds the system prompt from the
+    # flow Definition, and parses the structured JSON response.
+    class Client
+      attr_reader :adapter, :model
+
+      # @param adapter [Adapter] LLM provider adapter (e.g. OpenAIAdapter)
+      # @param model [String] model identifier (default: "gpt-4o-mini")
+      def initialize(adapter:, model: "gpt-4o-mini")
+        @adapter = adapter
+        @model = model
+      end
+
+      # Sends the introduction text to the LLM with a system prompt built from
+      # the Definition, and returns a hash of extracted step answers.
+      #
+      # @param definition [Definition] flow definition (used to build system prompt)
+      # @param introduction_text [String] user's free-form introduction
+      # @return [Hash<Symbol, Object>] step_id => extracted value
+      # @raise [LLMError] on response parsing failures
+      def parse_introduction(definition:, introduction_text:)
+        system_prompt = SystemPromptBuilder.new(definition).build
+        response_text = adapter.chat(
+          system_prompt: system_prompt,
+          user_prompt: introduction_text,
+          model: model
+        )
+        parse_response(response_text, definition)
+      end
+
+      private
+
+      def parse_response(text, definition)
+        json_str = extract_json(text)
+        raw = JSON.parse(json_str, symbolize_names: true)
+
+        raw.each_with_object({}) do |(step_id, value), result|
+          next unless definition.steps.key?(step_id)
+
+          node = definition.step(step_id)
+          result[step_id] = coerce_value(value, node.type)
+        end
+      rescue JSON::ParserError => e
+        raise LLMError, "Failed to parse LLM response as JSON: #{e.message}"
+      end
+
+      def extract_json(text)
+        # LLM may wrap JSON in markdown code fences
+        match = text.match(/```(?:json)?\s*\n?(.*?)\n?\s*```/m)
+        match ? match[1].strip : text.strip
+      end
+
+      def coerce_value(value, type)
+        case type
+        when :number
+          value.is_a?(Numeric) ? value : value.to_i
+        when :multi_select
+          Array(value)
+        when :number_matrix
+          return {} unless value.is_a?(Hash)
+
+          value.transform_values { |v| v.is_a?(Numeric) ? v : v.to_i }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm/openai_adapter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module FlowEngine
+  module LLM
+    # OpenAI adapter using the ruby_llm gem. Configures the API key
+    # and delegates chat calls to RubyLLM's conversation interface.
+    class OpenAIAdapter < Adapter
+      # @param api_key [String, nil] OpenAI API key; falls back to OPENAI_API_KEY env var
+      # @raise [LLMError] if no API key is available
+      def initialize(api_key: nil)
+        super()
+        @api_key = api_key || ENV.fetch("OPENAI_API_KEY", nil)
+        raise LLMError, "OpenAI API key not provided and OPENAI_API_KEY not set" unless @api_key
+      end
+
+      # @param system_prompt [String] system instructions
+      # @param user_prompt [String] user's text
+      # @param model [String] OpenAI model identifier
+      # @return [String] response content from the LLM
+      def chat(system_prompt:, user_prompt:, model: "gpt-4o-mini")
+        configure_ruby_llm!
+        conversation = RubyLLM.chat(model: model)
+        response = conversation.with_instructions(system_prompt).ask(user_prompt)
+        response.content
+      end
+
+      private
+
+      def configure_ruby_llm!
+        RubyLLM.configure do |config|
+          config.openai_api_key = @api_key
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm/sensitive_data_filter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Scans introduction text for sensitive data patterns (SSN, ITIN, EIN,
+    # bank account numbers) and raises {SensitiveDataError} if any are found.
+    # This prevents sensitive information from being sent to an LLM.
+    module SensitiveDataFilter
+      # SSN: 3 digits, dash, 2 digits, dash, 4 digits (e.g. 123-45-6789)
+      SSN_PATTERN = /\b\d{3}-\d{2}-\d{4}\b/
+
+      # ITIN: 9XX-XX-XXXX where first digit is 9
+      ITIN_PATTERN = /\b9\d{2}-\d{2}-\d{4}\b/
+
+      # EIN: 2 digits, dash, 7 digits (e.g. 12-3456789)
+      EIN_PATTERN = /\b\d{2}-\d{7}\b/
+
+      # Nine consecutive digits (SSN/ITIN without dashes)
+      NINE_DIGITS_PATTERN = /\b\d{9}\b/
+
+      PATTERNS = {
+        "SSN" => SSN_PATTERN,
+        "ITIN" => ITIN_PATTERN,
+        "EIN" => EIN_PATTERN,
+        "SSN/ITIN (no dashes)" => NINE_DIGITS_PATTERN
+      }.freeze
+
+      # Checks text for sensitive data patterns.
+      #
+      # @param text [String] introduction text to scan
+      # @raise [SensitiveDataError] if any sensitive patterns are detected
+      def self.check!(text)
+        detected = PATTERNS.each_with_object([]) do |(label, pattern), found|
+          found << label if text.match?(pattern)
+        end
+
+        return if detected.empty?
+
+        raise SensitiveDataError,
+              "Introduction contains sensitive information (#{detected.join(", ")}). " \
+              "Please remove all SSN, ITIN, EIN, and account numbers before proceeding."
+      end
+    end
+  end
+end

data/lib/flowengine/llm/system_prompt_builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Builds the system prompt for the LLM from the static template
+    # and dynamic step metadata from the flow Definition.
+    class SystemPromptBuilder
+      TEMPLATE_PATH = File.expand_path("../../../resources/prompts/generic-dsl-intake.j2", __dir__)
+
+      # @param definition [Definition] flow definition to describe
+      # @param template_path [String] path to the static prompt template
+      def initialize(definition, template_path: TEMPLATE_PATH)
+        @definition = definition
+        @template_path = template_path
+      end
+
+      # @return [String] complete system prompt (static template + step descriptions + response format)
+      def build
+        [static_prompt, steps_description, response_format].join("\n\n")
+      end
+
+      private
+
+      def static_prompt
+        File.read(@template_path)
+      end
+
+      def steps_description
+        lines = ["## Flow Steps\n"]
+        @definition.steps.each_value { |node| append_step_description(lines, node) }
+        lines.join("\n")
+      end
+
+      def append_step_description(lines, node)
+        lines << "### Step: `#{node.id}`"
+        lines << "- **Type**: #{node.type}"
+        lines << "- **Question**: #{node.question}"
+        append_options(lines, node) if node.options&.any?
+        lines << "- **Fields**: #{node.fields.join(", ")}" if node.fields&.any?
+        lines << ""
+      end
+
+      def append_options(lines, node)
+        if node.option_labels
+          formatted = node.option_labels.map { |key, label| "#{key} (#{label})" }.join(", ")
+          lines << "- **Options**: #{formatted}"
+          lines << "- **Use the option keys in your response, not the labels**"
+        else
+          lines << "- **Options**: #{node.options.join(", ")}"
+        end
+      end
+
+      def response_format
+        <<~PROMPT
+          ## Response Format
+
+          Respond with ONLY a valid JSON object mapping step IDs (as strings) to extracted values.
+          Only include steps where you can confidently extract an answer from the user's text.
+          Do not guess or fabricate answers. If unsure, omit that step.
+
+          Value types by step type:
+          - `single_select`: one of the listed option strings
+          - `multi_select`: an array of matching option strings
+          - `number`: an integer
+          - `text`: extracted text string
+          - `number_matrix`: a hash mapping field names to integers (e.g. {"RealEstate": 2, "LLC": 1})
+
+          Example: {"filing_status": "single", "dependents": 2, "income_types": ["W2", "Business"]}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/flowengine/llm.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "llm/adapter"
+require_relative "llm/openai_adapter"
+require_relative "llm/sensitive_data_filter"
+require_relative "llm/system_prompt_builder"
+require_relative "llm/client"
+
+module FlowEngine
+  # Namespace for LLM integration: adapters, system prompt building,
+  # sensitive data filtering, and the high-level Client.
+  module LLM
+  end
+end

data/lib/flowengine/node.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # A single step in the flow: question metadata, input config, and conditional transitions.
+  # Used by {Engine} to determine the next step and by UI/export to render the step.
+  #
+  # @attr_reader id [Symbol] unique step identifier
+  # @attr_reader type [Symbol] input type (e.g. :multi_select, :number_matrix)
+  # @attr_reader question [String] prompt text for the step
+  # @attr_reader options [Array, nil] option keys for select steps; nil for other types
+  # @attr_reader option_labels [Hash, nil] key => display label mapping (nil when options are plain strings)
+  # @attr_reader fields [Array, nil] field names for number_matrix etc.; nil otherwise
+  # @attr_reader transitions [Array<Transition>] ordered list of conditional next-step rules
+  # @attr_reader visibility_rule [Rules::Base, nil] rule controlling whether this node is visible (DAG mode)
   class Node
-    attr_reader :id, :type, :question, :options, :fields, :transitions, :visibility_rule
+    attr_reader :id, :type, :question, :options, :option_labels, :fields, :transitions, :visibility_rule
 
+    # @param id [Symbol] step id
+    # @param type [Symbol] step/input type
+    # @param question [String] label/prompt
+    # @param decorations [Object, nil] optional UI decorations (not used by engine)
+    # @param options [Array, Hash, nil] option list or key=>label hash for select steps
+    # @param fields [Array, nil] field list for matrix-style steps
+    # @param transitions [Array<Transition>] conditional next-step transitions (default: [])
+    # @param visibility_rule [Rules::Base, nil] optional rule for visibility (default: always visible)
     def initialize(id:, # rubocop:disable Metrics/ParameterLists
                    type:,
                    question:,
@@ -16,22 +35,48 @@ module FlowEngine
       @type = type
       @question = question
       @decorations = decorations
-      @options = options&.freeze
+      extract_options(options)
       @fields = fields&.freeze
       @transitions = transitions.freeze
       @visibility_rule = visibility_rule
       freeze
     end
 
+    # Resolves the next step id from current answers by evaluating transitions in order.
+    #
+    # @param answers [Hash] current answer state (step_id => value)
+    # @return [Symbol, nil] id of the next step, or nil if no transition matches (flow end)
     def next_step_id(answers)
       match = transitions.find { |t| t.applies?(answers) }
       match&.target
     end
 
+    # Whether this node should be considered visible given current answers (for DAG/visibility).
+    #
+    # @param answers [Hash] current answer state
+    # @return [Boolean] true if no visibility_rule, else result of rule evaluation
     def visible?(answers)
       return true if visibility_rule.nil?
 
       visibility_rule.evaluate(answers)
     end
+
+    private
+
+    # Normalizes options: a Hash is split into keys (options) and the full hash (option_labels);
+    # an Array is stored as-is with nil option_labels.
+    def extract_options(raw)
+      case raw
+      when Hash
+        @options = raw.keys.map(&:to_s).freeze
+        @option_labels = raw.transform_keys(&:to_s).freeze
+      when Array
+        @options = raw.freeze
+        @option_labels = nil
+      else
+        @options = nil
+        @option_labels = nil
+      end
+    end
   end
 end

data/lib/flowengine/rules/all.rb

@@ -2,19 +2,26 @@
 
 module FlowEngine
   module Rules
+    # Composite rule: logical AND of multiple sub-rules. All must be true.
+    #
+    # @attr_reader rules [Array<Base>] sub-rules to evaluate
     class All < Base
       attr_reader :rules
 
+      # @param rules [Array<Base>] one or more rules (arrays are flattened)
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if every sub-rule evaluates to true
       def evaluate(answers)
         rules.all? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [String] e.g. "(rule1 AND rule2 AND rule3)"
       def to_s
         "(#{rules.join(" AND ")})"
       end

data/lib/flowengine/rules/any.rb

@@ -2,19 +2,26 @@
 
 module FlowEngine
   module Rules
+    # Composite rule: logical OR of multiple sub-rules. At least one must be true.
+    #
+    # @attr_reader rules [Array<Base>] sub-rules to evaluate
     class Any < Base
       attr_reader :rules
 
+      # @param rules [Array<Base>] one or more rules (arrays are flattened)
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if any sub-rule evaluates to true
       def evaluate(answers)
         rules.any? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [String] e.g. "(rule1 OR rule2 OR rule3)"
       def to_s
         "(#{rules.join(" OR ")})"
       end

data/lib/flowengine/rules/base.rb

@@ -2,11 +2,20 @@
 
 module FlowEngine
   module Rules
+    # Abstract base for rule AST nodes. Subclasses implement {#evaluate} and {#to_s}
+    # for use in transitions and visibility conditions.
     class Base
+      # Evaluates the rule against the current answer context.
+      #
+      # @param _answers [Hash] step_id => value
+      # @return [Boolean]
       def evaluate(_answers)
         raise NotImplementedError, "#{self.class}#evaluate must be implemented"
       end
 
+      # Human-readable representation (e.g. for graph labels).
+      #
+      # @return [String]
       def to_s
         raise NotImplementedError, "#{self.class}#to_s must be implemented"
       end

data/lib/flowengine/rules/contains.rb

@@ -2,9 +2,16 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (as an array) includes the given value.
+    # Used for multi-select steps (e.g. "BusinessOwnership in earnings").
+    #
+    # @attr_reader field [Symbol] answer key (step id)
+    # @attr_reader value [Object] value that must be present in the array
     class Contains < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Object] value to check for
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +19,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if answers[field] (as array) includes value
       def evaluate(answers)
         Array(answers[field]).include?(value)
       end
 
+      # @return [String] e.g. "BusinessOwnership in earnings"
       def to_s
         "#{value} in #{field}"
       end