inquirex 0.2.0

data/lib/inquirex/rules/not_empty.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Rules
+    # Rule: the answer for the given field is present and not empty.
+    class NotEmpty < Base
+      attr_reader :field
+
+      def initialize(field)
+        super()
+        @field = field.to_sym
+        freeze
+      end
+
+      def evaluate(answers)
+        val = answers[@field]
+        return false if val.nil?
+        return false if val.respond_to?(:empty?) && val.empty?
+
+        true
+      end
+
+      def to_h
+        { "op" => "not_empty", "field" => @field.to_s }
+      end
+
+      def to_s
+        "#{@field} is not empty"
+      end
+
+      def self.from_h(hash)
+        field = hash["field"] || hash[:field]
+        new(field)
+      end
+    end
+  end
+end

data/lib/inquirex/transition.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # 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.
+  # Can carry a `requires_server` flag for steps that need a server round-trip (e.g. LLM steps).
+  #
+  # @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)
+  # @attr_reader requires_server [Boolean] whether this transition needs a server round-trip
+  class Transition
+    attr_reader :target, :rule, :requires_server
+
+    # @param target [Symbol] next step id
+    # @param rule [Rules::Base, nil] optional condition (nil = always)
+    # @param requires_server [Boolean] whether this edge needs server evaluation
+    def initialize(target:, rule: nil, requires_server: false)
+      @target = target.to_sym
+      @rule = rule
+      @requires_server = requires_server
+      freeze
+    end
+
+    # Human-readable label for the condition.
+    #
+    # @return [String] rule#to_s or "always"
+    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?
+
+      @rule.evaluate(answers)
+    end
+
+    # Serializes to a plain Hash for JSON output.
+    #
+    # @return [Hash]
+    def to_h
+      hash = { "to" => @target.to_s }
+      hash["rule"] = @rule.to_h if @rule
+      hash["requires_server"] = true if @requires_server
+      hash
+    end
+
+    # Deserializes from a plain Hash.
+    #
+    # @param hash [Hash] with string or symbol keys
+    # @return [Transition]
+    def self.from_h(hash)
+      target = hash["to"] || hash[:to]
+      rule_hash = hash["rule"] || hash[:rule]
+      requires_server = hash["requires_server"] || hash[:requires_server] || false
+      rule = rule_hash ? Rules::Base.from_h(rule_hash) : nil
+      new(target:, rule:, requires_server:)
+    end
+  end
+end

data/lib/inquirex/validation/adapter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Validation
+    # Result of validating a step answer.
+    #
+    # @attr_reader errors [Array<String>] validation error messages (empty when valid)
+    class Result
+      attr_reader :errors
+
+      # @param valid [Boolean]
+      # @param errors [Array<String>]
+      def initialize(valid:, errors: [])
+        @valid = valid
+        @errors = errors.freeze
+        freeze
+      end
+
+      # @return [Boolean]
+      def valid?
+        @valid
+      end
+    end
+
+    # Abstract adapter for step-level validation. Implement #validate to plug in
+    # dry-validation, ActiveModel::Validations, JSON Schema, or any other validator.
+    class Adapter
+      # @param _node [Node] the current step (for schema/constraints)
+      # @param _input [Object] value submitted by the user
+      # @return [Result]
+      def validate(_node, _input)
+        raise NotImplementedError, "#{self.class}#validate must be implemented"
+      end
+    end
+  end
+end

data/lib/inquirex/validation/null_adapter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Validation
+    # No-op validator: always accepts any input.
+    # Used by default when no validation adapter is configured.
+    class NullAdapter < Adapter
+      def validate(_node, _input)
+        Result.new(valid: true)
+      end
+    end
+  end
+end

data/lib/inquirex/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Inquirex
+  VERSION = "0.2.0"
+end

data/lib/inquirex.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "inquirex/version"
+require_relative "inquirex/errors"
+
+# Rules subsystem
+require_relative "inquirex/rules/base"
+require_relative "inquirex/rules/contains"
+require_relative "inquirex/rules/equals"
+require_relative "inquirex/rules/greater_than"
+require_relative "inquirex/rules/less_than"
+require_relative "inquirex/rules/not_empty"
+require_relative "inquirex/rules/all"
+require_relative "inquirex/rules/any"
+
+# Core graph objects
+require_relative "inquirex/transition"
+require_relative "inquirex/evaluator"
+require_relative "inquirex/node"
+require_relative "inquirex/definition"
+require_relative "inquirex/answers"
+
+# Validation
+require_relative "inquirex/validation/adapter"
+require_relative "inquirex/validation/null_adapter"
+
+# DSL
+require_relative "inquirex/dsl"
+require_relative "inquirex/dsl/rule_helpers"
+require_relative "inquirex/dsl/step_builder"
+require_relative "inquirex/dsl/flow_builder"
+
+# Engine
+require_relative "inquirex/engine/state_serializer"
+require_relative "inquirex/engine"
+
+# Graph utilities
+require_relative "inquirex/graph/mermaid_exporter"
+
+# Declarative, rules-driven questionnaire engine for building conditional intake forms,
+# qualification wizards, and branching surveys.
+#
+# @example Define a flow
+#   definition = Inquirex.define id: "tax-intake-2025" do
+#     meta title: "Tax Preparation Intake", subtitle: "Let's understand your situation"
+#     start :filing_status
+#
+#     ask :filing_status do
+#       type :enum
+#       question "What is your filing status?"
+#       options single: "Single", married_jointly: "Married Filing Jointly"
+#       transition to: :dependents
+#     end
+#
+#     ask :dependents do
+#       type :integer
+#       question "How many dependents?"
+#       default 0
+#       transition to: :done
+#     end
+#
+#     say :done do
+#       text "Thank you!"
+#     end
+#   end
+#
+#   engine = Inquirex::Engine.new(definition)
+#   engine.answer("single")
+#   engine.answer(2)
+#   engine.advance              # past the :done say step
+#   engine.finished?            # => true
+#
+# @example JSON round-trip
+#   json = definition.to_json
+#   restored = Inquirex::Definition.from_json(json)
+#
+module Inquirex
+  # Builds an immutable Definition from the declarative DSL block.
+  #
+  # @param id [String, nil] optional flow identifier
+  # @param version [String] semver (default: "1.0.0")
+  # @yield context of DSL::FlowBuilder
+  # @return [Definition]
+  def self.define(id: nil, version: "1.0.0", &)
+    builder = DSL::FlowBuilder.new(id:, version:)
+    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 Inquirex.define { ... }
+  # @return [Definition]
+  # @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 Errors::DefinitionError, "DSL syntax error: #{e.message}"
+  rescue StandardError => e
+    raise Errors::DefinitionError, "DSL evaluation error: #{e.message}"
+  end
+end

data/sig/inquirex.rbs

@@ -0,0 +1,4 @@
+module Inquirex
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: inquirex
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Inquirex lets you define multi-step questionnaires as directed graphs
+  with conditional branching, using a conversational DSL (ask, say, mention) and an
+  AST-based rule system (contains, equals, greater_than, all, any). The engine walks
+  the graph, collects structured answers, and serializes everything to JSON — making
+  it the ideal backbone for cross-platform intake forms where the frontend is a chat
+  widget, a terminal, or a mobile app. Framework-agnostic, zero dependencies, thread-safe
+  immutable definitions.
+email:
+- kigster@gmail.com
+executables:
+- inquirex
+extensions: []
+extra_rdoc_files: []
+files:
+- ".relaxed_rubocop.yml"
+- ".rub"
+- ".ruby-version"
+- ".secrets.baseline"
+- Brewfile
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/inquirex
+- justfile
+- lefthook.yml
+- lib/inquirex.rb
+- lib/inquirex/answers.rb
+- lib/inquirex/definition.rb
+- lib/inquirex/dsl.rb
+- lib/inquirex/dsl/flow_builder.rb
+- lib/inquirex/dsl/rule_helpers.rb
+- lib/inquirex/dsl/step_builder.rb
+- lib/inquirex/engine.rb
+- lib/inquirex/engine/state_serializer.rb
+- lib/inquirex/errors.rb
+- lib/inquirex/evaluator.rb
+- lib/inquirex/graph/mermaid_exporter.rb
+- lib/inquirex/node.rb
+- lib/inquirex/rules/all.rb
+- lib/inquirex/rules/any.rb
+- lib/inquirex/rules/base.rb
+- lib/inquirex/rules/contains.rb
+- lib/inquirex/rules/equals.rb
+- lib/inquirex/rules/greater_than.rb
+- lib/inquirex/rules/less_than.rb
+- lib/inquirex/rules/not_empty.rb
+- lib/inquirex/transition.rb
+- lib/inquirex/validation/adapter.rb
+- lib/inquirex/validation/null_adapter.rb
+- lib/inquirex/version.rb
+- sig/inquirex.rbs
+homepage: https://github.com/kigster/inquirex
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/inquirex
+  source_code_uri: https://github.com/kigster/inquirex
+  changelog_uri: https://github.com/kigster/inquirex/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A declarative, rules-driven questionnaire engine for building conditionally-branching
+  intake forms, qualification wizards, and surveys in pure Ruby.
+test_files: []