flowengine 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 758428572c105952cb5cf538db6ff0307b60c2a5cbf6187344664d2d063d680a
-  data.tar.gz: e4b3db255b71a7faa3f54f024d96440dbf62aaa383d4a01d96ac5bff58517bcb
+  metadata.gz: c6118d723586350e431080d822f01dbda45c9cc58257dd812e4d3dd7c30f8de6
+  data.tar.gz: 606d8ac60526863acb699c166b396d00baa29fdedb009df4c4a4b6bfb4a783a0
 SHA512:
-  metadata.gz: 6ebe4ebeaf8f47846fe4e831457de894a43e0e544c0f99453ecb9f6d1d535edcef2f8e5f83fc866984e731c865d1e0b6b8ecc3aa46e64b220fb44942441f3491
-  data.tar.gz: 6447ed169da61924456f6f7007b6373ad8f42cc03a667aa3fff7a39198a42b458811e477401c2df385a588466cb85b783ffc8cbf6e187d6a8b2cd8b81cc28112
+  metadata.gz: 00c92c2094931b5c4d427aec5e2de4bce98d733be459aadd367ce58f3d64564c7332c53d8810d37d1f5d95352439572fe2252eb6068a4fa9278c0e1cef223c78
+  data.tar.gz: d9bc34f2cfeb87ee7e6b6bc75e429903db85d4d2482a517240da2ab995bdd38202a03f3585f54a00e5e1d263751cf9f82225e34303889bbb67cdcbc0a7e47e92

data/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY="sk-proj-..."

data/.envrc

@@ -1,2 +1,6 @@
 PATH_add bin
 PATH_add exe
+
+if [[ -f .env ]]; then
+  eval "$(cat .env | sed '/^#.*/d; /^$/d; s/^/export /g')"
+fi

data/.rubocop_todo.yml

@@ -1,12 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-05 18:28:58 UTC using RuboCop version 1.85.0.
+# on 2026-03-10 19:57:08 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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 3
+# Offense count: 5
 # Configuration parameters: EnforcedStyle, AllowedGems.
 # SupportedStyles: Gemfile, gems.rb, gemspec
 Gemspec/DevelopmentDependencies:
@@ -18,16 +18,11 @@ Gemspec/DevelopmentDependencies:
 Metrics/AbcSize:
   Max: 18
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
   Max: 9
 
-# Offense count: 1
-# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
-Metrics/ParameterLists:
-  Max: 7
-
 # Offense count: 5
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call

data/README.md

@@ -1,6 +1,6 @@
 # FlowEngine
 
-[![RSpec](https://github.com/kigster/flowengine/actions/workflows/rspec.yml/badge.svg)](https://github.com/kigster/flowengine/actions/workflows/rspec.yml) [![RuboCop](https://github.com/kigster/flowengine/actions/workflows/rubocop.yml/badge.svg)](https://github.com/kigster/flowengine/actions/workflows/rubocop.yml)
+[![RSpec](https://github.com/kigster/flowengine/actions/workflows/rspec.yml/badge.svg)](https://github.com/kigster/flowengine/actions/workflows/rspec.yml)   [![RuboCop](https://github.com/kigster/flowengine/actions/workflows/rubocop.yml/badge.svg)](https://github.com/kigster/flowengine/actions/workflows/rubocop.yml)   ![Coverage](docs/badges/coverage_badge.svg)
 
 This gem is the foundation of collecting complex multi-branch information from a user using a flow definition written in Ruby DSL. It shouldn't take too long to learn the DSL even for a non-technical person.
 
@@ -37,6 +37,9 @@ require "flowengine"
 
 # 1. Define a flow
 definition = FlowEngine.define do
+  introduction label: "What are your favorite cocktails?",
+               placeholder: "Old Fashion, Whisky Sour, etc",
+               maxlength: 2000
   start :name
 
   step :name do
@@ -95,7 +98,123 @@ engine.history
 
 ### Using the `flowengine-cli` gem to Generate the JSON Answers File
 
+## 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.
+
+### Defining an Introduction
+
+Add the `introduction` command to your flow definition:
+
+```ruby
+definition = FlowEngine.define do
+  start :filing_status
+
+  introduction label: "Tell us about your tax situation",
+               placeholder: "e.g. I am married, filing jointly, with 2 dependents...",
+               maxlength: 2000  # optional character limit
+
+  step :filing_status do
+    type :single_select
+    question "What is your filing status?"
+    options %w[single married_filing_jointly head_of_household]
+    transition to: :dependents
+  end
+
+  step :dependents do
+    type :number
+    question "How many dependents?"
+    transition to: :income_types
+  end
+
+  step :income_types do
+    type :multi_select
+    question "Select income types"
+    options %w[W2 1099 Business Investment]
+  end
+end
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `label` | Yes | Text shown above the input field |
+| `placeholder` | No | Ghost text inside the text area (default: `""`) |
+| `maxlength` | No | Maximum character count (default: `nil` = unlimited) |
+
+### 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")
+
+# 2. Create the engine and submit the introduction
+engine = FlowEngine::Engine.new(definition)
+engine.submit_introduction(
+  "I am married filing jointly with 2 dependents, W2 and business income",
+  llm_client: client
+)
+
+# 3. The LLM pre-fills answers and the engine auto-advances
+engine.answers
+# => { filing_status: "married_filing_jointly", dependents: 2,
+#      income_types: ["W2", "Business"] }
+
+engine.current_step_id    # => nil (all steps pre-filled in this case)
+engine.introduction_text  # => "I am married filing jointly with 2 dependents, ..."
+engine.finished?          # => true
+```
+
+If the LLM can only extract some answers, the engine stops at the first unanswered step and the user continues the flow normally from there.
+
+### Sensitive Data Protection
+
+Before any text reaches the LLM, `submit_introduction` scans for sensitive data patterns:
+
+- **SSN**: `123-45-6789`
+- **ITIN**: `912-34-5678`
+- **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.
+
+```ruby
+engine.submit_introduction("My SSN is 123-45-6789", llm_client: client)
+# => raises FlowEngine::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:
+
+```ruby
+class MyAnthropicAdapter < FlowEngine::LLM::Adapter
+  def initialize(api_key:)
+    super()
+    @api_key = api_key
+  end
+
+  def chat(system_prompt:, user_prompt:, model:)
+    # Call your LLM API here
+    # Must return the response text (expected to be a JSON string)
+  end
+end
+
+adapter = MyAnthropicAdapter.new(api_key: ENV["ANTHROPIC_API_KEY"])
+client = FlowEngine::LLM::Client.new(adapter: adapter, model: "claude-sonnet-4-20250514")
+```
+
+### State Persistence
+
+The `introduction_text` is included in state serialization:
+
+```ruby
+state = engine.to_state
+# => { current_step_id: ..., answers: { ... }, history: [...], introduction_text: "..." }
+
+restored = FlowEngine::Engine.from_state(definition, state)
+restored.introduction_text  # => "I am married filing jointly..."
+```
 
 ## Architecture
 
@@ -108,13 +227,18 @@ The core has **zero UI logic**, **zero DB logic**, and **zero framework dependen
 | Component | Responsibility |
 |-----------|---------------|
 | `FlowEngine.define` | DSL entry point; returns a frozen `Definition` |
-| `Definition` | Immutable container of the flow graph (nodes + start step) |
+| `Introduction` | Immutable config for the introduction step (label, placeholder, maxlength) |
+| `Definition` | Immutable container of the flow graph (nodes + start step + introduction) |
 | `Node` | A single step: type, question, options/fields, transitions, visibility |
 | `Transition` | A directed edge with an optional rule condition |
 | `Rules::*` | AST nodes for conditional logic (`Contains`, `Equals`, `All`, etc.) |
 | `Evaluator` | Evaluates rules against the current answer store |
-| `Engine` | Stateful runtime: tracks current step, answers, and history |
+| `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::OpenAIAdapter` | OpenAI implementation via `ruby_llm` gem |
+| `LLM::Client` | High-level: builds prompt, calls adapter, parses JSON response |
+| `LLM::SensitiveDataFilter` | Rejects text containing SSN, ITIN, EIN patterns |
 | `Graph::MermaidExporter` | Exports the flow definition as a Mermaid diagram |
 
 ## The DSL
@@ -127,6 +251,11 @@ Every flow starts with `FlowEngine.define`, which returns a **frozen, immutable*
 definition = FlowEngine.define do
   start :first_step     # Required: which node to begin at
 
+  # Optional: collect free-form text before the flow, parsed by LLM
+  introduction label: "Describe your situation",
+               placeholder: "Type here...",
+               maxlength: 2000
+
   step :first_step do
     # step configuration...
   end
@@ -311,9 +440,11 @@ engine = FlowEngine::Engine.new(definition)
 | `engine.current_step_id` | `Symbol` or `nil` | The ID of the current step |
 | `engine.current_step` | `Node` or `nil` | The current Node object |
 | `engine.answer(value)` | `nil` | Records the answer and advances |
+| `engine.submit_introduction(text, llm_client:)` | `nil` | LLM-parses text, pre-fills answers, auto-advances |
 | `engine.finished?` | `Boolean` | `true` when there are no more steps |
 | `engine.answers` | `Hash` | All collected answers `{ step_id => value }` |
 | `engine.history` | `Array<Symbol>` | Ordered list of visited step IDs |
+| `engine.introduction_text` | `String` or `nil` | The raw introduction text submitted |
 | `engine.definition` | `Definition` | The immutable flow definition |
 
 ### Error Handling
@@ -336,6 +467,18 @@ FlowEngine.define do
   end
 end
 # => raises FlowEngine::DefinitionError
+
+# Sensitive data in introduction
+engine.submit_introduction("My SSN is 123-45-6789", llm_client: client)
+# => raises FlowEngine::SensitiveDataError
+
+# Introduction exceeds maxlength
+engine.submit_introduction("A" * 3000, llm_client: client)
+# => raises FlowEngine::ValidationError
+
+# Missing API key or LLM response parsing failure
+FlowEngine::LLM::OpenAIAdapter.new  # without OPENAI_API_KEY
+# => raises FlowEngine::LLMError
 ```
 
 ## Validation
@@ -896,7 +1039,7 @@ FlowEngine is the core of a three-gem architecture:
 
 | Gem | Purpose |
 |-----|---------|
-| **`flowengine`** (this gem) | Core engine — pure Ruby, no Rails, no DB, no UI |
+| **`flowengine`** (this gem) | Core engine + LLM introduction parsing (depends on `ruby_llm`) |
 | **`flowengine-cli`** | Terminal wizard adapter using [TTY Toolkit](https://ttytoolkit.org/) + Dry::CLI |
 | **`flowengine-rails`** | Rails Engine with ActiveRecord persistence and web views |
 

data/docs/badges/coverage_badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#4c1" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">100%</text>
+    <text x="80" y="14">100%</text>
+  </g>
+</svg>

data/justfile

@@ -41,6 +41,12 @@ doc:
     @bundle exec rake doc
     @open ./doc/index.html
 
+clean:
+    @rm -rf pkg
+    @rm -rf coverage
+
+release:
+    @bundle exec rake release
 
 check-all: lint test
 

data/lib/flowengine/definition.rb

@@ -7,14 +7,16 @@ module FlowEngine
   # @attr_reader start_step_id [Symbol] id of the first step in the flow
   # @attr_reader steps [Hash<Symbol, Node>] frozen map of step id => node (read-only)
   class Definition
-    attr_reader :start_step_id, :steps
+    attr_reader :start_step_id, :steps, :introduction
 
     # @param start_step_id [Symbol] id of the initial step
     # @param nodes [Hash<Symbol, Node>] all steps keyed by id
+    # @param introduction [Introduction, nil] optional introduction config (label + placeholder)
     # @raise [DefinitionError] if start_step_id is not present in nodes
-    def initialize(start_step_id:, nodes:)
+    def initialize(start_step_id:, nodes:, introduction: nil)
       @start_step_id = start_step_id
       @steps = nodes.freeze
+      @introduction = introduction
       validate!
       freeze
     end

data/lib/flowengine/dsl/flow_builder.rb

@@ -10,6 +10,7 @@ module FlowEngine
       def initialize
         @start_step_id = nil
         @nodes = {}
+        @introduction = nil
       end
 
       # Sets the entry step id for the flow.
@@ -19,6 +20,16 @@ module FlowEngine
         @start_step_id = step_id
       end
 
+      # Configures an introduction step that collects free-form text before the flow begins.
+      # The LLM parses this text to pre-fill answers for subsequent steps.
+      #
+      # @param label [String] text shown above the input field
+      # @param placeholder [String] text shown inside the empty text area
+      # @param maxlength [Integer, nil] maximum character count for the text (nil = unlimited)
+      def introduction(label:, placeholder: "", maxlength: nil)
+        @introduction = Introduction.new(label: label, placeholder: placeholder, maxlength: maxlength)
+      end
+
       # Defines one step by id; the block is evaluated in a {StepBuilder} context.
       #
       # @param id [Symbol] step id
@@ -37,7 +48,7 @@ module FlowEngine
         raise DefinitionError, "No start step defined" if @start_step_id.nil?
         raise DefinitionError, "No steps defined" if @nodes.empty?
 
-        Definition.new(start_step_id: @start_step_id, nodes: @nodes)
+        Definition.new(start_step_id: @start_step_id, nodes: @nodes, introduction: @introduction)
       end
     end
   end

data/lib/flowengine/engine.rb

@@ -8,8 +8,9 @@ module FlowEngine
   # @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})
@@ -19,6 +20,7 @@ module FlowEngine
       @history = []
       @current_step_id = definition.start_step_id
       @validator = validator
+      @introduction_text = nil
       @history << @current_step_id
     end
 
@@ -49,14 +51,32 @@ 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, and history (string/symbol keys as stored)
+    # @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
 
@@ -115,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
@@ -124,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

@@ -18,4 +18,10 @@ module FlowEngine
 
   # 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/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

@@ -7,18 +7,19 @@ module FlowEngine
   # @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] choices for multi_select; nil for other types
+  # @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, nil] option list for multi_select
+    # @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)
@@ -34,7 +35,7 @@ module FlowEngine
       @type = type
       @question = question
       @decorations = decorations
-      @options = options&.freeze
+      extract_options(options)
       @fields = fields&.freeze
       @transitions = transitions.freeze
       @visibility_rule = visibility_rule
@@ -59,5 +60,23 @@ module FlowEngine
 
       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/version.rb

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

data/lib/flowengine.rb

@@ -13,12 +13,14 @@ 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"
 
 # Declarative flow definition and execution engine for wizards, intake forms, and
 # multi-step decision graphs. Separates flow logic, data schema, and UI rendering.

data/resources/prompts/generic-dsl-intake.j2

@@ -0,0 +1,60 @@
+## Context 
+
+You are a generic intake assistant for a professional services firm. You are given a Ruby DSL that defines the intake flow.  You do not need to run the flow, but you need to understand the questions and it's structure.
+The gem will follow the flow to ask the questions in the correct order and will fill out the JSON data structure that is defined by the DSL, 
+and keep asking question until all required questions are answered.
+
+## Instructions for LLM
+
+I'd like to add a new DSL command called `introduction` with sub-arguments `label` (something that's shown above the input field) and 
+`placeholder` which is the text that will show up inside the text area before the user starts typing. 
+
+If this field is present in the DSL, we are to collect user's free-form text into a new field `engine.introduction()`. 
+
+Before the first step begins we must check if the introduction is non-empty, and if so the gem should take that response and via a AI Wrapper class that's instantiated with the name of the LLM model and API key, and adapter for different LLM APIs, should invoke whatever adapter is passed. For now let's create only OpenAI adapter. This class will use RubyLLM or any other gem that works to call OpenAI API. The user prompt will be the context of the user entry in `engine.introduction`. The system prompt is this file. 
+
+## What is the purpose of this step?
+
+The gem currently has:
+
+  1. DSL → Ruby objects (FlowEngine.define { ... } → Definition/Node/Transition/Rule objects)
+  2. DSL from string (FlowEngine.load_dsl(text) — evaluates Ruby source code, not JSON)
+  3. Engine state serialization (Engine#to_state / Engine.from_state — a simple hash of current_step_id, answers, history)
+  4. Mermaid export (Graph::MermaidExporter — outputs diagram syntax)
+
+The answers the user provides are stored in memory only — in the Engine instance's @answers hash (Hash<Symbol, Object>).
+
+```ruby
+  engine = FlowEngine::Engine.new(definition)
+  engine.answer("Alice")        # stores { name: "Alice" }
+  engine.answer(25)             # stores { name: "Alice", age: 25 }
+  engine.answers                # => { name: "Alice", age: 25 }
+```
+
+### How the Data is Stored
+
+The gem provides `Engine#to_state` which returns a plain Ruby hash:
+
+```ruby
+{ current_step_id: :age, answers: { name: "Alice" }, history: [:name, :age] }`
+```
+
+And `Engine.from_state(definition, hash)` to restore from it.
+
+### The job of the LLM
+
+The job of the LLM is to parse the user's introduction and to identify the DSL steps that the user already provided the answers for, and fill them in. 
+If the answer can be extracted from the text, it should be stored in the engine, and that question should be skipped in the normal flow.
+
+## Rules 
+
+- NEVER ask for sensitive information: SSN, ITIN, full address, bank account numbers, or date of birth. 
+- REJECT any sensitive information, and repeat the introduction step if it contains SSN/EIN
+- In other words, if the user volunteers sensitive information, immediately warn them and discard it
+- Do not communicate with the user. Your job is to parse their response and place it into the appropriate answers within the DSL.
+
+## API KEY
+
+Check environment variables such as OPENAI_API_KEY before calling LLM.
+
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -9,6 +9,34 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
@@ -23,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -61,12 +103,13 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".env.example"
 - ".envrc"
 - ".rubocop_todo.yml"
-- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/badges/coverage_badge.svg
 - docs/floweingine-architecture.png
 - docs/flowengine-example.png
 - exe/flowengine
@@ -81,6 +124,13 @@ files:
 - lib/flowengine/errors.rb
 - lib/flowengine/evaluator.rb
 - lib/flowengine/graph/mermaid_exporter.rb
+- lib/flowengine/introduction.rb
+- lib/flowengine/llm.rb
+- lib/flowengine/llm/adapter.rb
+- lib/flowengine/llm/client.rb
+- lib/flowengine/llm/openai_adapter.rb
+- lib/flowengine/llm/sensitive_data_filter.rb
+- lib/flowengine/llm/system_prompt_builder.rb
 - lib/flowengine/node.rb
 - lib/flowengine/rules/all.rb
 - lib/flowengine/rules/any.rb
@@ -94,6 +144,7 @@ files:
 - lib/flowengine/validation/adapter.rb
 - lib/flowengine/validation/null_adapter.rb
 - lib/flowengine/version.rb
+- resources/prompts/generic-dsl-intake.j2
 - sig/flowengine.rbs
 homepage: https://github.com/kigster/flowengine
 licenses:

data/CHANGELOG.md

@@ -1,5 +0,0 @@
-## [Unreleased]
-
-## [0.1.0] - 2026-02-26
-
-- Initial release