flowengine 0.3.0 → 0.3.1

data/lib/flowengine/llm/adapter.rb

@@ -1,18 +1,80 @@
 # frozen_string_literal: true
 
+require "ruby_llm"
+
 module FlowEngine
   module LLM
-    # Abstract adapter for LLM API calls. Subclass and implement {#chat}
-    # to integrate with a specific provider (OpenAI, Anthropic, etc.).
+    # Abstract adapter for LLM API calls. Subclass and implement the class methods
+    # {.api_key_var_name} and {.default_model} to integrate with a specific provider.
+    # Thread-safe: RubyLLM configuration is protected by a mutex.
     class Adapter
+      CONFIGURE_MUTEX = Mutex.new
+
+      attr_reader :api_key, :model, :qualifier, :vendor
+
+      # @param api_key [String, nil] API key; falls back to env var from {.api_key_var_name}
+      # @param model [String, nil] model identifier; falls back to {.default_model}
+      # @param qualifier [Symbol] adapter qualifier (:top, :default, :fastest)
+      # @raise [Errors::NoAPIKeyFoundError] if no API key is available
+      def initialize(api_key: nil, model: nil, qualifier: :default)
+        @qualifier = qualifier
+        @api_key = api_key || ENV.fetch(self.class.api_key_var_name, nil)
+        @model = model || self.class.default_model
+        @vendor = self.class.provider
+
+        unless @api_key
+          raise ::FlowEngine::Errors::NoAPIKeyFoundError,
+                "#{vendor} API key not available ($#{self.class.api_key_var_name} not set)"
+        end
+
+        configure_ruby_llm!
+        freeze
+      end
+
       # 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"
+      # @param user_prompt [String] user's text
+      # @param model [String] model identifier (defaults to the adapter's model)
+      # @return [String] the LLM's response content
+      def chat(system_prompt:, user_prompt:, model: @model)
+        conversation = RubyLLM.chat(model: model)
+        response = conversation.with_instructions(system_prompt).ask(user_prompt)
+        response.content
+      end
+
+      # Derives the provider symbol from the class name.
+      # e.g. AnthropicAdapter => :anthropic, OpenAIAdapter => :openai
+      #
+      # @return [Symbol]
+      def self.provider
+        name.split("::").last.downcase.gsub("adapter", "").to_sym
+      end
+
+      # @return [String] name of the environment variable for this provider's API key
+      def self.api_key_var_name
+        raise NotImplementedError, "#{name}.api_key_var_name must be implemented"
+      end
+
+      # @return [String] default model identifier for this provider
+      def self.default_model
+        raise NotImplementedError, "#{name}.default_model must be implemented"
+      end
+
+      def inspect
+        "#<#{self.class.name} vendor=#{vendor} model=#{model} qualifier=#{qualifier}>"
+      end
+
+      alias to_s inspect
+
+      private
+
+      def configure_ruby_llm!
+        method_name = "#{vendor}_api_key="
+        key = api_key
+        CONFIGURE_MUTEX.synchronize do
+          RubyLLM.configure { |config| config.send(method_name, key) }
+        end
       end
     end
   end

data/lib/flowengine/llm/adapters.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Adapter classes are dynamically generated from resources/models.yml.
+    # Each vendor entry produces a subclass of {Adapter} with the correct
+    # api_key_var_name and default_model. Adding a new LLM provider is just
+    # a YAML entry — no Ruby file needed.
+    module Adapters
+      LLM::VENDOR_CONFIG.each_value do |properties|
+        class_name = properties["adapter"].split("::").last
+        env_var = properties["var"]
+        default = properties["default"]
+
+        klass = Class.new(Adapter) do
+          define_singleton_method(:api_key_var_name) { env_var }
+          define_singleton_method(:default_model) { default }
+        end
+
+        const_set(class_name, klass)
+      end
+    end
+  end
+end

data/lib/flowengine/llm/auto_client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Client that picks its adapter from the pre-loaded ADAPTERS registry.
+    # Requires {LLM.load!} to have been called first.
+    class AutoClient < Client
+      # @param qualifier [Symbol] which model tier to use (:top, :default, :fastest)
+      # @raise [Errors::LLMError] if no adapters have been loaded
+      def initialize(qualifier: :default)
+        raise ::FlowEngine::Errors::LLMError, "No adapters loaded. Call FlowEngine::LLM.load! first." if ADAPTERS.empty?
+
+        entry = ADAPTERS.values.first
+        adapter = entry[qualifier.to_s]
+        super(adapter: adapter, model: adapter.model)
+      end
+    end
+  end
+end

data/lib/flowengine/llm/client.rb

@@ -10,11 +10,11 @@ module FlowEngine
     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")
+      # @param adapter [Adapter] LLM provider adapter (e.g. Adapters::OpenAIAdapter)
+      # @param model [String, nil] model identifier; defaults to the adapter's model
+      def initialize(adapter:, model: nil)
         @adapter = adapter
-        @model = model
+        @model = model || adapter.model
       end
 
       # Sends the introduction text to the LLM with a system prompt built from
@@ -23,7 +23,7 @@ module FlowEngine
       # @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
+      # @raise [Errors::LLMError] on response parsing failures
       def parse_introduction(definition:, introduction_text:)
         system_prompt = SystemPromptBuilder.new(definition).build
         response_text = adapter.chat(
@@ -34,6 +34,35 @@ module FlowEngine
         parse_response(response_text, definition)
       end
 
+      # Sends user text to the LLM for an AI intake step and returns both
+      # extracted answers and an optional follow-up question.
+      #
+      # @param definition [Definition] flow definition
+      # @param user_text [String] user's free-form text
+      # @param answered [Hash<Symbol, Object>] already-answered steps
+      # @param conversation_history [Array<Hash>] prior rounds [{role:, text:}]
+      # @return [Hash] { answers: Hash<Symbol, Object>, follow_up: String|nil }
+      # @raise [Errors::LLMError] on response parsing failures
+      def parse_ai_intake(definition:, user_text:, answered: {}, conversation_history: [])
+        system_prompt = IntakePromptBuilder.new(
+          definition,
+          answered: answered,
+          conversation_history: conversation_history
+        ).build
+
+        response_text = adapter.chat(
+          system_prompt: system_prompt,
+          user_prompt: user_text,
+          model: model
+        )
+
+        parse_intake_response(response_text, definition)
+      end
+
+      def to_s
+        "#<#{self.class.name} adapter=#{adapter} model=#{model}>"
+      end
+
       private
 
       def parse_response(text, definition)
@@ -47,7 +76,7 @@ module FlowEngine
           result[step_id] = coerce_value(value, node.type)
         end
       rescue JSON::ParserError => e
-        raise LLMError, "Failed to parse LLM response as JSON: #{e.message}"
+        raise ::FlowEngine::Errors::LLMError, "Failed to parse LLM response as JSON: #{e.message}"
       end
 
       def extract_json(text)
@@ -70,6 +99,23 @@ module FlowEngine
           value
         end
       end
+
+      def parse_intake_response(text, definition)
+        json_str = extract_json(text)
+        raw = JSON.parse(json_str, symbolize_names: true)
+
+        answers_raw = raw[:answers] || {}
+        answers = answers_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
+
+        { answers: answers, follow_up: raw[:follow_up] }
+      rescue JSON::ParserError => e
+        raise ::FlowEngine::Errors::LLMError, "Failed to parse LLM response as JSON: #{e.message}"
+      end
     end
   end
 end

data/lib/flowengine/llm/intake_prompt_builder.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Builds system prompts for AI intake steps. Unlike SystemPromptBuilder (used for
+    # the definition-level introduction), this builder is aware of already-answered steps,
+    # conversation history, and instructs the LLM to optionally ask follow-up questions.
+    class IntakePromptBuilder
+      # @param definition [Definition] flow definition
+      # @param answered [Hash<Symbol, Object>] already-answered step_id => value pairs
+      # @param conversation_history [Array<Hash>] prior rounds: [{role:, text:}, ...]
+      def initialize(definition, answered: {}, conversation_history: [])
+        @definition = definition
+        @answered = answered
+        @conversation_history = conversation_history
+      end
+
+      # @return [String] system prompt for the LLM
+      def build
+        sections = [
+          context_section,
+          unanswered_steps_section,
+          answered_steps_section,
+          conversation_history_section,
+          response_format_section
+        ].compact
+
+        sections.join("\n\n")
+      end
+
+      private
+
+      def context_section
+        <<~PROMPT
+          ## Context
+
+          You are an intake assistant. The user is providing free-form text to answer
+          questions in a structured intake form. Your job is to:
+
+          1. Extract as many answers as you can from the user's text
+          2. If critical information is still missing, ask ONE concise follow-up question
+          3. If you have enough information or cannot reasonably ask more, return no follow-up
+
+          NEVER ask for sensitive information (SSN, ITIN, EIN, bank account numbers, date of birth).
+          Do not fabricate answers. Only extract what the user clearly stated.
+        PROMPT
+      end
+
+      def unanswered_steps_section
+        unanswered = @definition.steps.reject { |id, node| @answered.key?(id) || node.ai_intake? }
+        return nil if unanswered.empty?
+
+        lines = ["## Unanswered Steps (fill these from the user's text)\n"]
+        unanswered.each_value { |node| append_step_description(lines, node) }
+        lines.join("\n")
+      end
+
+      def answered_steps_section
+        return nil if @answered.empty?
+
+        lines = ["## Already Answered Steps (do not re-ask these)\n"]
+        @answered.each do |step_id, value|
+          next unless @definition.steps.key?(step_id)
+
+          node = @definition.step(step_id)
+          lines << "- **#{step_id}** (#{node.question}): `#{value.inspect}`"
+        end
+        lines << ""
+        lines.join("\n")
+      end
+
+      def conversation_history_section
+        return nil if @conversation_history.empty?
+
+        lines = ["## Conversation History\n"]
+        @conversation_history.each do |entry|
+          role = entry[:role] == :user ? "User" : "Assistant"
+          lines << "**#{role}**: #{entry[:text]}"
+          lines << ""
+        end
+        lines.join("\n")
+      end
+
+      def response_format_section
+        <<~PROMPT
+          ## Response Format
+
+          Respond with ONLY a valid JSON object with two keys:
+
+          1. `"answers"` — a JSON object mapping step IDs to extracted values. Only include
+             steps where you can confidently extract an answer. Value types:
+             - `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
+
+          2. `"follow_up"` — either a string with ONE concise clarifying question, or `null`
+             if you have no more questions. Focus on the most important unanswered step.
+
+          Example:
+          ```json
+          {
+            "answers": {"filing_status": "married_joint", "dependents": 2},
+            "follow_up": "What types of income do you have — W2, 1099, business, or investment?"
+          }
+          ```
+        PROMPT
+      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
+    end
+  end
+end

data/lib/flowengine/llm/provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    # Immutable data class representing an LLM provider configuration.
+    Provider = Data.define(:name, :env_var, :adapter_class) do
+      def available?
+        !ENV.fetch(env_var, nil).nil?
+      end
+    end
+  end
+end

data/lib/flowengine/llm/sensitive_data_filter.rb

@@ -36,7 +36,7 @@ module FlowEngine
 
         return if detected.empty?
 
-        raise SensitiveDataError,
+        raise ::FlowEngine::Errors::SensitiveDataError,
               "Introduction contains sensitive information (#{detected.join(", ")}). " \
               "Please remove all SSN, ITIN, EIN, and account numbers before proceeding."
       end

data/lib/flowengine/llm.rb

@@ -1,48 +1,107 @@
 # frozen_string_literal: true
 
-require_relative "llm/adapter"
-require_relative "llm/openai_adapter"
-require_relative "llm/anthropic_adapter"
-require_relative "llm/gemini_adapter"
-require_relative "llm/sensitive_data_filter"
-require_relative "llm/system_prompt_builder"
-require_relative "llm/client"
+require "yaml"
 
 module FlowEngine
   # Namespace for LLM integration: adapters, system prompt building,
   # sensitive data filtering, and the high-level Client.
   module LLM
-    # Provider registry: ordered by priority (first match wins).
-    # Each entry maps an explicit kwarg name to [env_var, adapter_class, default_model].
-    PROVIDERS = [
-      [:anthropic_api_key, "ANTHROPIC_API_KEY", AnthropicAdapter, AnthropicAdapter::DEFAULT_MODEL],
-      [:openai_api_key, "OPENAI_API_KEY", OpenAIAdapter, "gpt-4o-mini"],
-      [:gemini_api_key, "GEMINI_API_KEY", GeminiAdapter, GeminiAdapter::DEFAULT_MODEL]
-    ].freeze
-
-    # Builds an adapter and Client by detecting which API key is available
-    # in the environment. Priority: Anthropic > OpenAI > Gemini.
-    #
-    # @param anthropic_api_key [String, nil] explicit Anthropic key
-    # @param openai_api_key [String, nil] explicit OpenAI key
-    # @param gemini_api_key [String, nil] explicit Gemini key
-    # @param model [String, nil] override model; auto-selected if nil
-    # @return [Client] configured client with the detected adapter
-    # @raise [LLMError] if no API key is found for any provider
-    def self.auto_client(anthropic_api_key: nil, openai_api_key: nil, gemini_api_key: nil, model: nil)
-      explicit_keys = { anthropic_api_key: anthropic_api_key, openai_api_key: openai_api_key,
-                        gemini_api_key: gemini_api_key }
-
-      PROVIDERS.each do |kwarg, env_var, adapter_class, default_model|
-        key = explicit_keys[kwarg] || ENV.fetch(env_var, nil)
-        next unless key
-
-        adapter = adapter_class.new(api_key: key)
-        return Client.new(adapter: adapter, model: model || default_model)
+    # Path to the models.yml file (overridable via env var)
+    MODELS_YAML_PATH = ENV.fetch(
+      "FLOWENGINE_LLM_MODELS_PATH",
+      File.join(::FlowEngine::ROOT, "resources", "models.yml")
+    )
+
+    # Vendor config loaded once from models.yml — used by Adapters module
+    # to dynamically generate adapter classes and by auto_client for detection.
+    VENDOR_CONFIG = (YAML.load_file(MODELS_YAML_PATH).dig("models", "vendors") || {}).freeze
+
+    # Provider priority for auto-detection: [kwarg_name, env_var, adapter_class_name]
+    PROVIDERS = VENDOR_CONFIG.map do |_vendor, properties|
+      [properties["var"].downcase.to_sym, properties["var"], properties["adapter"]]
+    end.freeze
+
+    # Pre-loaded adapters registry: { "vendor" => { "qualifier" => adapter } }
+    ADAPTERS = {} # rubocop:disable Style/MutableConstant -- intentionally mutable registry
+    ADAPTERS_MUTEX = Mutex.new
+    QUALIFIERS = %i[top default fastest].freeze
+
+    class << self
+      # Builds an adapter and Client by detecting which API key is available.
+      # Priority order matches models.yml vendor order (Anthropic > OpenAI > Gemini).
+      #
+      # @param anthropic_api_key [String, nil] explicit Anthropic key
+      # @param openai_api_key [String, nil] explicit OpenAI key
+      # @param gemini_api_key [String, nil] explicit Gemini key
+      # @param model [String, nil] override model; adapter default if nil
+      # @return [Client] configured client with the detected adapter
+      # @raise [Errors::LLMError] if no API key is found for any provider
+      def auto_client(anthropic_api_key: nil, openai_api_key: nil, gemini_api_key: nil, model: nil)
+        explicit_keys = {
+          anthropic_api_key: anthropic_api_key,
+          openai_api_key: openai_api_key,
+          gemini_api_key: gemini_api_key
+        }
+
+        PROVIDERS.each do |kwarg, env_var, adapter_class_name|
+          key = explicit_keys[kwarg] || ENV.fetch(env_var, nil)
+          next unless key
+
+          adapter_class = ::FlowEngine.constantize(adapter_class_name)
+          adapter = adapter_class.new(api_key: key)
+          return Client.new(adapter: adapter, model: model || adapter.model)
+        end
+
+        env_vars = PROVIDERS.map { |_, env_var, _| env_var }.join(", ")
+        raise ::FlowEngine::Errors::LLMError, "No LLM API key found. Set #{env_vars}"
+      end
+
+      # Pre-loads adapters from models.yml into ADAPTERS registry.
+      # Call explicitly when you want pre-instantiated adapters (e.g. in bin/ask).
+      def load!(file = MODELS_YAML_PATH)
+        return if @adapters_loaded
+
+        raise ::FlowEngine::Errors::ConfigurationError, "Models file #{file} not found" unless file && File.exist?(file)
+
+        count = 0
+        ::YAML.load_file(file)["models"]["vendors"].each_pair do |vendor, properties|
+          api_key = ENV.fetch(properties["var"], nil)
+          unless api_key
+            warn "API key for #{vendor} not found in environment, vendor disabled."
+            next
+          end
+
+          adapter_class = ::FlowEngine.constantize(properties["adapter"])
+          QUALIFIERS.each do |qualifier|
+            model = properties[qualifier.to_s]
+            adapter = adapter_class.new(api_key: api_key, model: model, qualifier: qualifier)
+            add_adapter(adapter)
+            count += 1
+          end
+        end
+        @adapters_loaded = true
+        warn "Loaded #{count} adapters for #{ADAPTERS.keys.size} vendors."
+      end
+
+      # Looks up a pre-loaded adapter by vendor and qualifier.
+      def [](vendor:, qualifier: :default)
+        ADAPTERS.dig(vendor.to_s, qualifier.to_s)
       end
 
-      env_vars = PROVIDERS.map { |_, env_var, _, _| env_var }.join(", ")
-      raise FlowEngine::LLMError, "No LLM API key found. Set #{env_vars}"
+      # Resets the loaded state (useful for testing).
+      def reset!
+        ADAPTERS_MUTEX.synchronize { ADAPTERS.clear }
+        @adapters_loaded = false
+      end
+
+      private
+
+      def add_adapter(adapter)
+        ADAPTERS_MUTEX.synchronize do
+          ADAPTERS[adapter.vendor.to_s] ||= {}
+          ADAPTERS[adapter.vendor.to_s][adapter.qualifier.to_s] = adapter
+        end
+      end
     end
   end
 end

data/lib/flowengine/node.rb

@@ -5,15 +5,17 @@ module FlowEngine
   # 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 type [Symbol] input type (e.g. :multi_select, :number_matrix, :ai_intake)
   # @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)
+  # @attr_reader max_clarifications [Integer] max follow-up rounds for :ai_intake steps (default: 0)
   class Node
-    attr_reader :id, :type, :question, :options, :option_labels, :fields, :transitions, :visibility_rule
+    attr_reader :id, :type, :question, :options, :option_labels, :fields,
+                :transitions, :visibility_rule, :max_clarifications
 
     # @param id [Symbol] step id
     # @param type [Symbol] step/input type
@@ -23,6 +25,7 @@ module FlowEngine
     # @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)
+    # @param max_clarifications [Integer] max follow-up rounds for :ai_intake (default: 0)
     def initialize(id:, # rubocop:disable Metrics/ParameterLists
                    type:,
                    question:,
@@ -30,7 +33,8 @@ module FlowEngine
                    options: nil,
                    fields: nil,
                    transitions: [],
-                   visibility_rule: nil)
+                   visibility_rule: nil,
+                   max_clarifications: 0)
       @id = id
       @type = type
       @question = question
@@ -39,9 +43,15 @@ module FlowEngine
       @fields = fields&.freeze
       @transitions = transitions.freeze
       @visibility_rule = visibility_rule
+      @max_clarifications = max_clarifications
       freeze
     end
 
+    # @return [Boolean] true if this is an AI intake step
+    def ai_intake?
+      type == :ai_intake
+    end
+
     # Resolves the next step id from current answers by evaluating transitions in order.
     #
     # @param answers [Hash] current answer state (step_id => value)

data/lib/flowengine/version.rb

@@ -2,5 +2,5 @@
 
 module FlowEngine
   # Semantic version of the flowengine gem (major.minor.patch).
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/flowengine.rb

@@ -1,26 +1,14 @@
 # frozen_string_literal: true
 
-require_relative "flowengine/version"
-require_relative "flowengine/errors"
-require_relative "flowengine/rules/base"
-require_relative "flowengine/rules/contains"
-require_relative "flowengine/rules/equals"
-require_relative "flowengine/rules/greater_than"
-require_relative "flowengine/rules/less_than"
-require_relative "flowengine/rules/not_empty"
-require_relative "flowengine/rules/all"
-require_relative "flowengine/rules/any"
-require_relative "flowengine/evaluator"
-require_relative "flowengine/transition"
-require_relative "flowengine/node"
-require_relative "flowengine/introduction"
-require_relative "flowengine/definition"
-require_relative "flowengine/validation/adapter"
-require_relative "flowengine/validation/null_adapter"
-require_relative "flowengine/engine"
-require_relative "flowengine/dsl"
-require_relative "flowengine/graph/mermaid_exporter"
-require_relative "flowengine/llm"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "flowengine" => "FlowEngine",
+  "llm" => "LLM",
+  "dsl" => "DSL"
+)
+loader.setup
 
 # Declarative flow definition and execution engine for wizards, intake forms, and
 # multi-step decision graphs. Separates flow logic, data schema, and UI rendering.
@@ -45,11 +33,14 @@ require_relative "flowengine/llm"
 #   engine.current_step_id # => :business_details
 #
 module FlowEngine
+  # Root directory of the flowengine gem
+  ROOT = File.expand_path("..", __dir__)
+
   # Builds an immutable {Definition} from the declarative DSL block.
   #
   # @yield context of {DSL::FlowBuilder} (start, step, and rule helpers)
   # @return [Definition] frozen flow definition with start step and nodes
-  # @raise [DefinitionError] if no start step or no steps are defined
+  # @raise [Errors::DefinitionError] if no start step or no steps are defined
   def self.define(&)
     builder = DSL::FlowBuilder.new
     builder.instance_eval(&)
@@ -61,14 +52,22 @@ module FlowEngine
   #
   # @param text [String] Ruby source containing FlowEngine.define { ... }
   # @return [Definition] the definition produced by evaluating the DSL
-  # @raise [DefinitionError] on syntax or evaluation errors
+  # @raise [Errors::DefinitionError] on syntax or evaluation errors
   def self.load_dsl(text)
     # rubocop:disable Security/Eval
     eval(text, TOPLEVEL_BINDING.dup, "(dsl)", 1)
     # rubocop:enable Security/Eval
   rescue SyntaxError => e
-    raise DefinitionError, "DSL syntax error: #{e.message}"
+    raise Errors::DefinitionError, "DSL syntax error: #{e.message}"
   rescue StandardError => e
-    raise DefinitionError, "DSL evaluation error: #{e.message}"
+    raise Errors::DefinitionError, "DSL evaluation error: #{e.message}"
+  end
+
+  # Resolves a fully-qualified constant name string to the actual constant.
+  #
+  # @param name [String] e.g. "FlowEngine::LLM::Adapters::AnthropicAdapter"
+  # @return [Class, Module]
+  def self.constantize(name)
+    name.split("::").inject(Object) { |mod, const| mod.const_get(const) }
   end
 end