flowengine 0.1.1 → 0.2.1

data/lib/flowengine/rules/equals.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field equals the given value.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Object] expected value
     class Equals < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Object] expected value
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if answers[field] == value
       def evaluate(answers)
         answers[field] == value
       end
 
+      # @return [String] e.g. "marital_status == Married"
       def to_s
         "#{field} == #{value}"
       end

data/lib/flowengine/rules/greater_than.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (coerced to integer) is greater than the threshold.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Integer] threshold
     class GreaterThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Integer] threshold
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers (field value is coerced with to_i)
+      # @return [Boolean] true if answers[field].to_i > value
       def evaluate(answers)
         answers[field].to_i > value
       end
 
+      # @return [String] e.g. "business_income > 100000"
       def to_s
         "#{field} > #{value}"
       end

data/lib/flowengine/rules/less_than.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (coerced to integer) is less than the threshold.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Integer] threshold
     class LessThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Integer] threshold
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers (field value is coerced with to_i)
+      # @return [Boolean] true if answers[field].to_i < value
       def evaluate(answers)
         answers[field].to_i < value
       end
 
+      # @return [String] e.g. "age < 18"
       def to_s
         "#{field} < #{value}"
       end

data/lib/flowengine/rules/not_empty.rb

@@ -2,15 +2,21 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field is present and not empty (nil or empty? => false).
+    #
+    # @attr_reader field [Symbol] answer key
     class NotEmpty < Base
       attr_reader :field
 
+      # @param field [Symbol] answer key
       def initialize(field)
         super()
         @field = field
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] false if nil or empty, true otherwise
       def evaluate(answers)
         val = answers[field]
         return false if val.nil?
@@ -19,6 +25,7 @@ module FlowEngine
         true
       end
 
+      # @return [String] e.g. "name is not empty"
       def to_s
         "#{field} is not empty"
       end

data/lib/flowengine/transition.rb

@@ -1,19 +1,33 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # A single edge from one step to another, optionally guarded by a rule.
+  # Transitions are evaluated in order; the first whose rule is true determines the next step.
+  #
+  # @attr_reader target [Symbol] id of the step to go to when this transition applies
+  # @attr_reader rule [Rules::Base, nil] condition; nil means unconditional (always applies)
   class Transition
     attr_reader :target, :rule
 
+    # @param target [Symbol] next step id
+    # @param rule [Rules::Base, nil] optional condition (nil = always)
     def initialize(target:, rule: nil)
       @target = target
       @rule = rule
       freeze
     end
 
+    # Human-readable label for the condition (e.g. for graph export).
+    #
+    # @return [String] rule#to_s or "always" when rule is nil
     def condition_label
       rule ? rule.to_s : "always"
     end
 
+    # Whether this transition should be taken given current answers.
+    #
+    # @param answers [Hash] current answer state
+    # @return [Boolean] true if rule is nil or rule evaluates to true
     def applies?(answers)
       return true if rule.nil?
 

data/lib/flowengine/validation/adapter.rb

@@ -2,21 +2,34 @@
 
 module FlowEngine
   module Validation
+    # Result of validating a step answer: either valid or a list of error messages.
+    #
+    # @attr_reader errors [Array<String>] validation error messages (empty when valid)
     class Result
       attr_reader :errors
 
+      # @param valid [Boolean] whether the input passed validation
+      # @param errors [Array<String>] error messages (default: [])
       def initialize(valid:, errors: [])
         @valid = valid
         @errors = errors.freeze
         freeze
       end
 
+      # @return [Boolean] true if validation passed
       def valid?
         @valid
       end
     end
 
+    # Abstract adapter for step-level validation. Implement {#validate} to plug in
+    # dry-validation, JSON Schema, or other validators; the engine does not depend on a specific one.
     class Adapter
+      # Validates the user's input for the given step.
+      #
+      # @param _node [Node] the current step (for schema/constraints)
+      # @param _input [Object] the value submitted by the user
+      # @return [Result] valid: true/false and optional errors list
       def validate(_node, _input)
         raise NotImplementedError, "#{self.class}#validate must be implemented"
       end

data/lib/flowengine/validation/null_adapter.rb

@@ -2,7 +2,11 @@
 
 module FlowEngine
   module Validation
+    # No-op validator: always accepts any input. Used by default when no validation adapter is given.
     class NullAdapter < Adapter
+      # @param _node [Node] ignored
+      # @param _input [Object] ignored
+      # @return [Result] always valid with no errors
       def validate(_node, _input)
         Result.new(valid: true, errors: [])
       end

data/lib/flowengine/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module FlowEngine
-  VERSION = "0.1.1"
+  # Semantic version of the flowengine gem (major.minor.patch).
+  VERSION = "0.2.1"
 end

data/lib/flowengine.rb

@@ -13,20 +13,55 @@ 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.
+#
+# @example Define and run a flow
+#   definition = FlowEngine.define do
+#     start :earnings
+#     step :earnings do
+#       type :multi_select
+#       question "What are your main earnings?"
+#       options %w[W2 1099 BusinessOwnership]
+#       transition to: :business_details, if: contains(:earnings, "BusinessOwnership")
+#     end
+#     step :business_details do
+#       type :number_matrix
+#       question "How many business types?"
+#       fields %w[RealEstate SCorp CCorp]
+#     end
+#   end
+#   engine = FlowEngine::Engine.new(definition)
+#   engine.answer(["W2", "BusinessOwnership"])
+#   engine.current_step_id # => :business_details
+#
 module FlowEngine
+  # 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
   def self.define(&)
     builder = DSL::FlowBuilder.new
     builder.instance_eval(&)
     builder.build
   end
 
+  # Evaluates a string of DSL code and returns the resulting definition.
+  # Intended for loading flow definitions from files or stored text.
+  #
+  # @param text [String] Ruby source containing FlowEngine.define { ... }
+  # @return [Definition] the definition produced by evaluating the DSL
+  # @raise [DefinitionError] on syntax or evaluation errors
   def self.load_dsl(text)
     # rubocop:disable Security/Eval
     eval(text, TOPLEVEL_BINDING.dup, "(dsl)", 1)

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.1
+  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