flowengine 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50117723ca62a9851b0c8091e2619132d6e2f849e62b765dadd5c0d0d5c601ad
-  data.tar.gz: 0024ae08e3d6068d0ed913067368ddd4764a83f9ffe1f44e4d9bdcef4f544757
+  metadata.gz: c6118d723586350e431080d822f01dbda45c9cc58257dd812e4d3dd7c30f8de6
+  data.tar.gz: 606d8ac60526863acb699c166b396d00baa29fdedb009df4c4a4b6bfb4a783a0
 SHA512:
-  metadata.gz: 8d3e5eb92cf044bed6e4a5408ed70452dc755234030e3a39785714864c09d2ba804592cca29005f304dab0fab95058f142602f0239e2f68ffa9826ef15bd748d
-  data.tar.gz: f889c3914f22d5a6cb4f439e202c318819e007a692f973bef4a288c4c4bbb34995aa65bf88bd5ddc799ee3ed684ae41066617300d7b3e67efe4e62437717149d
+  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.
 
@@ -8,10 +8,12 @@ This gem does not have any UI or an interactive component. It is used as the fou
 
 The simplest way to see this in action is to use the companion gem [`flowengine-cli`](https://rubygems.org/gems/flowengine-cli), which, given the flow DSL will walk the user through the questioniare according to the DSL flow definition, but using terminal UI and ASCII-based flow.
 
-A declarative flow engine for building rules-driven wizards and intake forms in pure Ruby.
+**A slightly different explanation is that it offere a declarative flow engine for building rules-driven wizards and intake forms in pure Ruby.**
 
-FlowEngine lets you define multi-step flows as **directed graphs** with **conditional branching**, evaluate transitions using an **AST-based rule system**, and collect structured answers through a **stateful runtime engine** — all without framework dependencies.
+> [!NOTE]
+> FlowEngine lets you define multi-step flows as **directed graphs** with **conditional branching**, evaluate transitions using an **AST-based rule system**, and collect structured answers through a **stateful runtime engine** — all without framework dependencies.
 
+> [!CAUTION]
 > **This is not a form builder.** It's a *Form Definition Engine* that separates flow logic, data schema, and UI rendering into independent concerns.
 
 ## Installation
@@ -35,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
@@ -93,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
 
@@ -106,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
@@ -125,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
@@ -309,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
@@ -334,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
@@ -894,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/Rakefile

@@ -26,7 +26,7 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt]
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
   t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
   t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end

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

@@ -36,6 +36,17 @@ format:
 lint: 
     @bundle exec rubocop
 
+# Generates library documentation into ./doc folder and opens the browser
+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

@@ -1,24 +1,39 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Immutable, versionable flow graph: maps step ids to {Node} objects and defines the entry point.
+  # Built by {DSL::FlowBuilder}; consumed by {Engine} for navigation.
+  #
+  # @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
 
-    def initialize(start_step_id:, nodes:)
+    # @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:, introduction: nil)
       @start_step_id = start_step_id
       @steps = nodes.freeze
+      @introduction = introduction
       validate!
       freeze
     end
 
+    # @return [Node] the node for the start step
     def start_step
       step(start_step_id)
     end
 
+    # @param id [Symbol] step id
+    # @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}" }
     end
 
+    # @return [Array<Symbol>] all step ids in the definition
     def step_ids
       steps.keys
     end

data/lib/flowengine/dsl/flow_builder.rb

@@ -2,29 +2,53 @@
 
 module FlowEngine
   module DSL
+    # Builds a {Definition} from the declarative DSL used in {FlowEngine.define}.
+    # Provides {#start} and {#step}; each step block is evaluated by {StepBuilder} with {RuleHelpers}.
     class FlowBuilder
       include RuleHelpers
 
       def initialize
         @start_step_id = nil
         @nodes = {}
+        @introduction = nil
       end
 
+      # Sets the entry step id for the flow.
+      #
+      # @param step_id [Symbol] id of the first step
       def start(step_id)
         @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
+      # @yield block evaluated in {StepBuilder} (type, question, options, transition, etc.)
       def step(id, &)
         builder = StepBuilder.new
         builder.instance_eval(&)
         @nodes[id] = builder.build(id)
       end
 
+      # Produces the frozen {Definition} from the accumulated start and steps.
+      #
+      # @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?
 
-        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/dsl/rule_helpers.rb

@@ -2,31 +2,53 @@
 
 module FlowEngine
   module DSL
+    # Factory methods for rule objects, included in {FlowBuilder} and {StepBuilder}.
+    # Use these inside step blocks for transition conditions and visible_if.
     module RuleHelpers
+      # @param field [Symbol] answer key (step id)
+      # @param value [Object] value to check for in the array
+      # @return [Rules::Contains]
       def contains(field, value)
         Rules::Contains.new(field, value)
       end
 
+      # @param field [Symbol] answer key
+      # @param value [Object] expected value
+      # @return [Rules::Equals]
       def equals(field, value)
         Rules::Equals.new(field, value)
       end
 
+      # @param field [Symbol] answer key (value coerced to integer for comparison)
+      # @param value [Integer] threshold
+      # @return [Rules::GreaterThan]
       def greater_than(field, value)
         Rules::GreaterThan.new(field, value)
       end
 
+      # @param field [Symbol] answer key (value coerced to integer for comparison)
+      # @param value [Integer] threshold
+      # @return [Rules::LessThan]
       def less_than(field, value)
         Rules::LessThan.new(field, value)
       end
 
+      # @param field [Symbol] answer key
+      # @return [Rules::NotEmpty]
       def not_empty(field)
         Rules::NotEmpty.new(field)
       end
 
+      # Logical AND of multiple rules.
+      # @param rules [Array<Rules::Base>] rules to combine
+      # @return [Rules::All]
       def all(*rules)
         Rules::All.new(*rules)
       end
 
+      # Logical OR of multiple rules.
+      # @param rules [Array<Rules::Base>] rules to combine
+      # @return [Rules::Any]
       def any(*rules)
         Rules::Any.new(*rules)
       end

data/lib/flowengine/dsl/step_builder.rb

@@ -2,6 +2,8 @@
 
 module FlowEngine
   module DSL
+    # Builds a single {Node} from step DSL (type, question, options, transitions, visibility).
+    # Used by {FlowBuilder#step}; includes {RuleHelpers} for transition/visibility conditions.
     class StepBuilder
       include RuleHelpers
 
@@ -15,34 +17,55 @@ module FlowEngine
         @decorations = nil
       end
 
+      # Sets the step/input type (e.g. :multi_select, :number_matrix).
+      # @param value [Symbol]
       def type(value)
         @type = value
       end
 
+      # Sets the prompt/label for the step.
+      # @param text [String]
       def question(text)
         @question = text
       end
 
+      # Sets the list of options for multi-select or choice steps.
+      # @param list [Array]
       def options(list)
         @options = list
       end
 
+      # Sets the list of field names for matrix-style steps (e.g. number_matrix).
+      # @param list [Array]
       def fields(list)
         @fields = list
       end
 
+      # Optional UI decorations (opaque to the engine).
+      # @param decorations [Object]
       def decorations(decorations)
         @decorations = decorations
       end
 
+      # Adds a conditional transition to another step. First matching transition wins.
+      #
+      # @param to [Symbol] target step id
+      # @param if_rule [Rules::Base, nil] condition (nil = unconditional)
       def transition(to:, if_rule: nil)
         @transitions << Transition.new(target: to, rule: if_rule)
       end
 
+      # Sets the visibility rule for this step (DAG mode: step shown only when rule is true).
+      #
+      # @param rule [Rules::Base]
       def visible_if(rule)
         @visibility_rule = rule
       end
 
+      # Builds the {Node} for the given step id from accumulated attributes.
+      #
+      # @param id [Symbol] step id
+      # @return [Node]
       def build(id)
         Node.new(
           id: id,

data/lib/flowengine/dsl.rb

@@ -5,6 +5,8 @@ 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.
   module DSL
   end
 end