flowengine 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6118d723586350e431080d822f01dbda45c9cc58257dd812e4d3dd7c30f8de6
-  data.tar.gz: 606d8ac60526863acb699c166b396d00baa29fdedb009df4c4a4b6bfb4a783a0
+  metadata.gz: 2cfa285d8ba7e6975cffead57c7a737c42ddb119be74e37edb617198c56d391c
+  data.tar.gz: 842c4b843cbdd83fceb49cb066bb49553d4d95a6d0cf2d1df891c8d553eb005b
 SHA512:
-  metadata.gz: 00c92c2094931b5c4d427aec5e2de4bce98d733be459aadd367ce58f3d64564c7332c53d8810d37d1f5d95352439572fe2252eb6068a4fa9278c0e1cef223c78
-  data.tar.gz: d9bc34f2cfeb87ee7e6b6bc75e429903db85d4d2482a517240da2ab995bdd38202a03f3585f54a00e5e1d263751cf9f82225e34303889bbb67cdcbc0a7e47e92
+  metadata.gz: 742b19a6eb3c667612ce74d83dab6f0402b02bf5cc0f808a4cf9c2070dfb649617e126a6674c7059465cf6654f0898d9d367bd483c6da4bffe8ec785ec5ae6c1
+  data.tar.gz: 225aae48aa9c12121c7a466a263ff66a5735064472720776cf17f0404b9d3a9f581107df57a8efa2d4071f3a635568b3b7ed37ff8d58f4b876f6b29af498e2fd

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-10 19:57:08 UTC using RuboCop version 1.85.1.
+# on 2026-03-11 14:01:54 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,11 +13,6 @@ Gemspec/DevelopmentDependencies:
   Exclude:
     - 'flowengine.gemspec'
 
-# Offense count: 1
-# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
-Metrics/AbcSize:
-  Max: 18
-
 # Offense count: 2
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:

data/README.md

@@ -98,6 +98,69 @@ engine.history
 
 ### Using the `flowengine-cli` gem to Generate the JSON Answers File
 
+---
+
+## LLM-Based DSL Capabilities & Environment Variables
+
+There are several environment variables that define which vendor and which model you can talk to should you choose to engage LLM in your decision logic.
+
+There is a very special YAML file that's provided with this gem, which locks in the list of supported vendors and three types of models per vendor:
+
+- best bang for the buck models
+- deep thinking and hard mode models
+- fastest models
+- *at some point we might also add the "cheapest".*
+
++The file [resources/models.yml](resources/models.yml) defines which models are available to the adapter. This file is used at the startup of the gem, to load and initialize all LLM Adapters for which we have the API Key defined in the environment. And for those we'll have at least three model names loaded:
+
+- `top:` — best results, likely the most expensive.
+- `default:` — default model, if the user of the adapter does not specify.
+- `fastest` — the fastest model from this vendor.
+
+Here is the contents of `resources/models.yml` verbatim:
+
+```yaml
+models:
+  version: "1.0"
+  date: "Wed Mar 11 02:35:39 PDT 2026"
+  vendors:
+    anthropic: 
+      adapter: "FlowEngine::LLM::Adapters::AnthropicAdapter"
+      var: "ANTHROPIC_API_KEY"
+      top: "claude-opus-4-6"
+      default: "claude-sonnet-4-6"
+      fastest: "claude-haiku-4-5-20251001"
+    openai:
+      adapter: "FlowEngine::LLM::Adapters::OpenAIAdapter"
+      var: "OPENAI_API_KEY"
+      top: "gpt-5.4"
+      default: "gpt-5-mini"
+      fastest: "gpt-5-nano"
+    gemini:
+      adapter: "FlowEngine::LLM::Adapters::GeminiAdapters"
+      var: "GEMINI_API_KEY"
+      top: "gemini-3.1-pro-preview"
+      default: "gemini-2.5-flash"
+      fastest: "gemini-2.5-flash-lite"
+```
+
+Notice how this file operates as almost a sort of glue for the gem: it explicitly tells you the names of variables to store your API keys, the class names of the corresponding Adapters, and the three models for each vendor:
+
+1. `:top`
+2. `:default`
+3. `:fastest`
+
+> [!IMPORTANT]
+>
+> The reason these models are extracted into a separate YAML file should be obvious: the contents of this list seems to change every week, and gem can remain at the same version for years. For this reason, the gem honors the environment variable `${FLOWENGINE_LLM_MODELS_PATH}` and will read the models and vendors from the file pointed to by that path environment variable. This is your door to better models, and other LLM vendors that RubyLLM supports.
+
+When the gem is loading, one of the first things it does is load this YAML file and instantiate the hash of pre-initialized adapters.
+
+Need an adapter to throw with your API call?
+
+```ruby
+FlowEngine::LLM[vendor: :anthropic, 'claude-opus-4-6']
+
 ## LLM-parsed Introduction
 
 FlowEngine supports an optional **introduction step** that collects free-form text from the user before the structured flow begins. An LLM parses this text to pre-fill answers, automatically skipping steps the user already answered in their introduction.
@@ -144,9 +207,13 @@ end
 ### Using the Introduction at Runtime
 
 ```ruby
-# 1. Configure an LLM adapter and client
-adapter = FlowEngine::LLM::OpenAIAdapter.new(api_key: ENV["OPENAI_API_KEY"])
-client = FlowEngine::LLM::Client.new(adapter: adapter, model: "gpt-4o-mini")
+# 1. Auto-detect adapter from environment (checks ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY)
+client = FlowEngine::LLM.auto_client
+
+# Or explicitly choose a provider:
+# client = FlowEngine::LLM.auto_client(anthropic_api_key: "sk-ant-...")
+# client = FlowEngine::LLM.auto_client(openai_api_key: "sk-...", model: "gpt-4o")
+# client = FlowEngine::LLM.auto_client(gemini_api_key: "AIza...")
 
 # 2. Create the engine and submit the introduction
 engine = FlowEngine::Engine.new(definition)
@@ -176,19 +243,27 @@ Before any text reaches the LLM, `submit_introduction` scans for sensitive data
 - **EIN**: `12-3456789`
 - **Nine consecutive digits**: `123456789`
 
-If detected, a `FlowEngine::SensitiveDataError` is raised immediately. The introduction text is discarded and no LLM call is made.
+If detected, a `FlowEngine::Errors::SensitiveDataError` is raised immediately. The introduction text is discarded and no LLM call is made.
 
 ```ruby
 engine.submit_introduction("My SSN is 123-45-6789", llm_client: client)
-# => raises FlowEngine::SensitiveDataError
+# => raises FlowEngine::Errors::SensitiveDataError
 ```
 
 ### Custom LLM Adapters
 
-The LLM integration uses an adapter pattern. The gem ships with an OpenAI adapter (via the [`ruby_llm`](https://github.com/crmne/ruby_llm) gem), but you can create adapters for any provider:
+The LLM integration uses an adapter pattern. The gem ships with three adapters (all via the [`ruby_llm`](https://github.com/crmne/ruby_llm) gem):
+
+| Adapter | Env Variable | Default Model |
+|---------|-------------|---------------|
+| `AnthropicAdapter` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| `OpenAIAdapter` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `GeminiAdapter` | `GEMINI_API_KEY` | `gemini-2.0-flash` |
+
+You can also create adapters for any other provider:
 
 ```ruby
-class MyAnthropicAdapter < FlowEngine::LLM::Adapter
+class MyCustomAdapter < FlowEngine::LLM::Adapter
   def initialize(api_key:)
     super()
     @api_key = api_key
@@ -200,8 +275,8 @@ class MyAnthropicAdapter < FlowEngine::LLM::Adapter
   end
 end
 
-adapter = MyAnthropicAdapter.new(api_key: ENV["ANTHROPIC_API_KEY"])
-client = FlowEngine::LLM::Client.new(adapter: adapter, model: "claude-sonnet-4-20250514")
+adapter = MyCustomAdapter.new(api_key: ENV["MY_API_KEY"])
+client = FlowEngine::LLM::Client.new(adapter: adapter, model: "my-model")
 ```
 
 ### State Persistence
@@ -236,8 +311,11 @@ The core has **zero UI logic**, **zero DB logic**, and **zero framework dependen
 | `Engine` | Stateful runtime: tracks current step, answers, history, and introduction |
 | `Validation::Adapter` | Interface for pluggable validation (dry-validation, JSON Schema, etc.) |
 | `LLM::Adapter` | Abstract interface for LLM API calls |
+| `LLM::AnthropicAdapter` | Anthropic/Claude implementation via `ruby_llm` gem |
 | `LLM::OpenAIAdapter` | OpenAI implementation via `ruby_llm` gem |
+| `LLM::GeminiAdapter` | Google Gemini implementation via `ruby_llm` gem |
 | `LLM::Client` | High-level: builds prompt, calls adapter, parses JSON response |
+| `LLM.auto_client` | Factory: auto-detects provider from environment API keys |
 | `LLM::SensitiveDataFilter` | Rejects text containing SSN, ITIN, EIN patterns |
 | `Graph::MermaidExporter` | Exports the flow definition as a Mermaid diagram |
 
@@ -452,11 +530,11 @@ engine = FlowEngine::Engine.new(definition)
 ```ruby
 # Answering after the flow is complete
 engine.answer("extra")
-# => raises FlowEngine::AlreadyFinishedError
+# => raises FlowEngine::Errors::AlreadyFinishedError
 
 # Referencing an unknown step in a definition
 definition.step(:nonexistent)
-# => raises FlowEngine::UnknownStepError
+# => raises FlowEngine::Errors::UnknownStepError
 
 # Invalid definition (start step doesn't exist)
 FlowEngine.define do
@@ -466,19 +544,19 @@ FlowEngine.define do
     question "Hello"
   end
 end
-# => raises FlowEngine::DefinitionError
+# => raises FlowEngine::Errors::DefinitionError
 
 # Sensitive data in introduction
 engine.submit_introduction("My SSN is 123-45-6789", llm_client: client)
-# => raises FlowEngine::SensitiveDataError
+# => raises FlowEngine::Errors::SensitiveDataError
 
 # Introduction exceeds maxlength
 engine.submit_introduction("A" * 3000, llm_client: client)
-# => raises FlowEngine::ValidationError
+# => raises FlowEngine::Errors::ValidationError
 
 # Missing API key or LLM response parsing failure
-FlowEngine::LLM::OpenAIAdapter.new  # without OPENAI_API_KEY
-# => raises FlowEngine::LLMError
+FlowEngine::LLM::Adapters::OpenAIAdapter.new  # without OPENAI_API_KEY
+# => raises FlowEngine::Errors::LLMError
 ```
 
 ## Validation
@@ -495,8 +573,8 @@ class FlowEngine::Validation::Adapter
 end
 
 # Result object
-FlowEngine::Validation::Result.new(valid: true, errors: [])
-FlowEngine::Validation::Result.new(valid: false, errors: ["must be a number"])
+FlowEngine::Errors::Validation::Result.new(valid: true, errors: [])
+FlowEngine::Errors::Validation::Result.new(valid: false, errors: ["must be a number"])
 ```
 
 ### Custom Validator Example
@@ -517,12 +595,12 @@ class MyValidator < FlowEngine::Validation::Adapter
       end
     end
 
-    FlowEngine::Validation::Result.new(valid: errors.empty?, errors: errors)
+    FlowEngine::Errors::Validation::Result.new(valid: errors.empty?, errors: errors)
   end
 end
 
 engine = FlowEngine::Engine.new(definition, validator: MyValidator.new)
-engine.answer("not_a_number")  # => raises FlowEngine::ValidationError
+engine.answer("not_a_number")  # => raises FlowEngine::Errors::ValidationError
 ```
 
 ## Mermaid Diagram Export

data/lib/flowengine/clarification_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  # Immutable result from an AI intake or clarification round.
+  #
+  # @attr_reader answered [Hash<Symbol, Object>] step_id => value pairs filled this round
+  # @attr_reader pending_steps [Array<Symbol>] step ids still unanswered after this round
+  # @attr_reader follow_up [String, nil] clarifying question from the LLM, or nil if done
+  # @attr_reader round [Integer] current clarification round (1-based)
+  ClarificationResult = Data.define(:answered, :pending_steps, :follow_up, :round) do
+    def initialize(answered: {}, pending_steps: [], follow_up: nil, round: 1)
+      super
+      freeze
+    end
+
+    # @return [Boolean] true when the LLM has no more questions or max rounds reached
+    def done?
+      follow_up.nil?
+    end
+  end
+end

data/lib/flowengine/definition.rb

@@ -30,7 +30,7 @@ module FlowEngine
     # @return [Node] the node for that step
     # @raise [UnknownStepError] if id is not in steps
     def step(id)
-      steps.fetch(id) { raise UnknownStepError, "Unknown step: #{id.inspect}" }
+      steps.fetch(id) { raise Errors::UnknownStepError, "Unknown step: #{id.inspect}" }
     end
 
     # @return [Array<Symbol>] all step ids in the definition
@@ -41,7 +41,9 @@ module FlowEngine
     private
 
     def validate!
-      raise DefinitionError, "Start step #{start_step_id.inspect} not found in nodes" unless steps.key?(start_step_id)
+      return if steps.key?(start_step_id)
+
+      raise Errors::DefinitionError, "Start step #{start_step_id.inspect} not found in nodes"
     end
   end
 end

data/lib/flowengine/dsl/flow_builder.rb

@@ -45,8 +45,8 @@ module FlowEngine
       # @return [Definition]
       # @raise [DefinitionError] if start was not set or no steps were defined
       def build
-        raise DefinitionError, "No start step defined" if @start_step_id.nil?
-        raise DefinitionError, "No steps defined" if @nodes.empty?
+        raise ::FlowEngine::Errors::DefinitionError, "No start step defined" if @start_step_id.nil?
+        raise ::FlowEngine::Errors::DefinitionError, "No steps defined" if @nodes.empty?
 
         Definition.new(start_step_id: @start_step_id, nodes: @nodes, introduction: @introduction)
       end

data/lib/flowengine/dsl/step_builder.rb

@@ -15,6 +15,7 @@ module FlowEngine
         @transitions = []
         @visibility_rule = nil
         @decorations = nil
+        @max_clarifications = 0
       end
 
       # Sets the step/input type (e.g. :multi_select, :number_matrix).
@@ -62,6 +63,13 @@ module FlowEngine
         @visibility_rule = rule
       end
 
+      # Sets the maximum number of clarification rounds for an :ai_intake step.
+      #
+      # @param count [Integer] max follow-up rounds (0 = one-shot, no clarifications)
+      def max_clarifications(count)
+        @max_clarifications = count
+      end
+
       # Builds the {Node} for the given step id from accumulated attributes.
       #
       # @param id [Symbol] step id
@@ -75,7 +83,8 @@ module FlowEngine
           fields: @fields,
           transitions: @transitions,
           visibility_rule: @visibility_rule,
-          decorations: @decorations
+          decorations: @decorations,
+          max_clarifications: @max_clarifications
         )
       end
     end

data/lib/flowengine/dsl.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "dsl/rule_helpers"
-require_relative "dsl/step_builder"
-require_relative "dsl/flow_builder"
-
 module FlowEngine
   # Namespace for the declarative flow DSL: {FlowBuilder} builds a {Definition} from blocks,
   # {StepBuilder} builds individual {Node}s, and {RuleHelpers} provide rule factory methods.

data/lib/flowengine/engine/state_serializer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  class Engine
+    # Handles state serialization and deserialization for Engine persistence.
+    # Normalizes string-keyed hashes (from JSON) to symbol-keyed hashes.
+    module StateSerializer
+      SYMBOLIZERS = {
+        current_step_id: ->(v) { v&.to_sym },
+        active_intake_step_id: ->(v) { v&.to_sym },
+        history: ->(v) { Array(v).map { |e| e&.to_sym } },
+        answers: ->(v) { symbolize_answers(v) },
+        conversation_history: ->(v) { symbolize_conversation_history(v) }
+      }.freeze
+
+      # Normalizes a state hash so step ids and history entries are symbols.
+      def self.symbolize_state(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, value), result|
+          sym_key = key.to_sym
+          result[sym_key] = SYMBOLIZERS.fetch(sym_key, ->(v) { v }).call(value)
+        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)
+
+        answers.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      end
+
+      # @param history [Array<Hash>] conversation history entries
+      # @return [Array<Hash>] same entries with symbolized keys and role
+      def self.symbolize_conversation_history(history)
+        return [] unless history.is_a?(Array)
+
+        history.map do |entry|
+          next entry unless entry.is_a?(Hash)
+
+          entry.each_with_object({}) do |(k, v), h|
+            sym_key = k.to_sym
+            h[sym_key] = sym_key == :role ? v.to_sym : v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/engine.rb

@@ -3,14 +3,9 @@
 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, :introduction_text
+  class Engine # rubocop:disable Metrics/ClassLength
+    attr_reader :definition, :answers, :history, :current_step_id, :introduction_text,
+                :clarification_round, :conversation_history
 
     # @param definition [Definition] the flow to run
     # @param validator [Validation::Adapter] validator for step answers (default: {Validation::NullAdapter})
@@ -21,6 +16,9 @@ module FlowEngine
       @current_step_id = definition.start_step_id
       @validator = validator
       @introduction_text = nil
+      @clarification_round = 0
+      @conversation_history = []
+      @active_intake_step_id = nil
       @history << @current_step_id
     end
 
@@ -42,10 +40,10 @@ module FlowEngine
     # @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?
+      raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?
 
       result = @validator.validate(current_step, value)
-      raise ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
+      raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
       answers[@current_step_id] = value
       advance_step
@@ -56,9 +54,6 @@ module FlowEngine
     #
     # @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)
@@ -68,65 +63,67 @@ module FlowEngine
       auto_advance_prefilled
     end
 
-    # Serializable state for persistence or resumption.
+    # Submits free-form text for the current AI intake step. Returns a ClarificationResult.
     #
-    # @return [Hash] current_step_id, answers, history, and introduction_text
+    # @param text [String] user's free-form text
+    # @param llm_client [LLM::Client] configured LLM client
+    # @return [ClarificationResult]
+    def submit_ai_intake(text, llm_client:)
+      node = current_step
+      raise Errors::EngineError, "Current step is not an AI intake step" unless node&.ai_intake?
+
+      LLM::SensitiveDataFilter.check!(text)
+
+      @active_intake_step_id = @current_step_id
+      @clarification_round = 1
+      @conversation_history = [{ role: :user, text: text }]
+
+      perform_intake_round(text, llm_client, node)
+    end
+
+    # Submits a clarification response for an ongoing AI intake conversation.
+    #
+    # @param text [String] user's response to the follow-up question
+    # @param llm_client [LLM::Client] configured LLM client
+    # @return [ClarificationResult]
+    def submit_clarification(text, llm_client:)
+      raise Errors::EngineError, "No active AI intake conversation to clarify" unless @active_intake_step_id
+
+      LLM::SensitiveDataFilter.check!(text)
+
+      node = @definition.step(@active_intake_step_id)
+      @clarification_round += 1
+      @conversation_history << { role: :user, text: text }
+
+      perform_intake_round(text, llm_client, node)
+    end
+
+    # Serializable state for persistence or resumption.
     def to_state
       {
         current_step_id: @current_step_id,
         answers: @answers,
         history: @history,
-        introduction_text: @introduction_text
+        introduction_text: @introduction_text,
+        clarification_round: @clarification_round,
+        conversation_history: @conversation_history,
+        active_intake_step_id: @active_intake_step_id
       }
     end
 
-    # Rebuilds an engine from a previously saved state (e.g. from DB or session).
+    # Rebuilds an engine from a previously saved state.
     #
     # @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 state_hash [Hash] hash with state keys (may be strings from JSON)
     # @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)
+      state = StateSerializer.symbolize_state(state_hash)
       engine = allocate
       engine.send(:restore_state, definition, state, validator)
       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)
-
-      hash.each_with_object({}) do |(key, value), result|
-        sym_key = key.to_sym
-        result[sym_key] = case sym_key
-                          when :current_step_id
-                            value&.to_sym
-                          when :history
-                            Array(value).map { |v| v&.to_sym }
-                          when :answers
-                            symbolize_answers(value)
-                          else
-                            value
-                          end
-      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)
-
-      answers.each_with_object({}) do |(key, value), result|
-        result[key.to_sym] = value
-      end
-    end
-
-    private_class_method :symbolize_state, :symbolize_answers
-
     private
 
     def restore_state(definition, state, validator)
@@ -136,12 +133,14 @@ module FlowEngine
       @answers = state[:answers] || {}
       @history = state[:history] || []
       @introduction_text = state[:introduction_text]
+      @clarification_round = state[:clarification_round] || 0
+      @conversation_history = state[:conversation_history] || []
+      @active_intake_step_id = state[:active_intake_step_id]
     end
 
     def advance_step
       node = definition.step(@current_step_id)
       next_id = node.next_step_id(answers)
-
       @current_step_id = next_id
       @history << next_id if next_id
     end
@@ -151,13 +150,58 @@ module FlowEngine
       return unless maxlength
       return if text.length <= maxlength
 
-      raise ValidationError, "Introduction text exceeds maxlength (#{text.length}/#{maxlength})"
+      raise Errors::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
+
+    def perform_intake_round(user_text, llm_client, node)
+      result = llm_client.parse_ai_intake(
+        definition: @definition, user_text: user_text,
+        answered: @answers, conversation_history: @conversation_history
+      )
+      @answers.merge!(result[:answers])
+      follow_up = resolve_follow_up(result[:follow_up], node)
+
+      build_clarification_result(result[:answers], follow_up)
+    end
+
+    def resolve_follow_up(follow_up, node)
+      if follow_up && @clarification_round <= node.max_clarifications
+        @conversation_history << { role: :assistant, text: follow_up }
+        follow_up
+      else
+        finalize_intake
+        nil
+      end
+    end
+
+    def build_clarification_result(round_answers, follow_up)
+      ClarificationResult.new(
+        answered: round_answers,
+        pending_steps: pending_non_intake_steps,
+        follow_up: follow_up,
+        round: @clarification_round
+      )
+    end
+
+    def finalize_intake
+      @answers[@active_intake_step_id] = conversation_summary
+      @active_intake_step_id = nil
+      advance_step
+      auto_advance_prefilled
+    end
+
+    def conversation_summary
+      @conversation_history.map { |e| "#{e[:role]}: #{e[:text]}" }.join("\n")
+    end
+
+    def pending_non_intake_steps
+      @definition.steps.each_with_object([]) do |(id, node), pending|
+        pending << id unless node.ai_intake? || @answers.key?(id)
+      end
+    end
   end
 end