inquirex 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a4701c7b2bb8ccf5a9da4a5a25e93be1cc4544371f2d9c1f48c478e04a9af75
-  data.tar.gz: 3192f545c283e0cfedf7eadec341f02d7984c0551ee1454714b51eb7fb1db250
+  metadata.gz: b7434e2fb6848ea3155939c7a1c49a6447652aa9ae08285bc1a3d3ed76d5019e
+  data.tar.gz: e01afc532faf0001fd6fb011a58c2f871a30e100581171df58a42eebab7be730
 SHA512:
-  metadata.gz: 66b1f3c05ad85be1bc8b70f05b669b540cc116b0f9a985393e7715614fa98a0974c631e7ca5cb709b29a2c000fd4f4eb535fea81c14959572e63be817069117d
-  data.tar.gz: 957265be4973894ff8d2a5b219a89c68196a880c63179e103c652fafd67cdb71fe1809a68db23e2b403ff72e1d4fc78810694c03bf58cb45aed02dcf13051443
+  metadata.gz: afa3f0101993f5ccfdf3e9a646bbd7fb8f6540cb93168f05e01541dccdf5ede38f5cf55922d09a3fe44e6551a7c9344b020394908a3ca3e094858f4eb1d17fa6
+  data.tar.gz: 248c2fc2a30480493e1b38ecefa3d619a8f533d7a641c5cc62acf04179b9e4c21761ee3cad6862c6ff34cb365ad9f3c94414b2c14f99194c633ae11895a3ec74

data/lib/inquirex/engine.rb

@@ -62,6 +62,8 @@ module Inquirex
       @completion_hook_errors = []
       @suggestions = {}
       @skipped = []
+      @snapshots = []
+      @rewound_answers = {}
       @history << @current_step_id
       skip_display_steps_if_needed
     end
@@ -119,6 +121,7 @@ module Inquirex
       raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
       node = current_step
+      push_snapshot
       @answers[@current_step_id] = value
       @suggestions.delete(@current_step_id)
       apply_accumulations(node, value)
@@ -133,6 +136,7 @@ module Inquirex
       raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?
 
       node = current_step
+      push_snapshot
       capture_transcript(Transcript.display_entry(node)) if node.display?
       advance_step
     end
@@ -166,6 +170,7 @@ module Inquirex
         if current_step.required?
 
       node = current_step
+      push_snapshot
       default = resolve_default(node)
       unless default.nil?
         @answers[@current_step_id] = default
@@ -177,6 +182,74 @@ module Inquirex
       advance_step
     end
 
+    # Undoes the user's last answer or skip: the engine returns to the most
+    # recent collecting step the user acted on, with answers, totals (including
+    # the :text transcript), skipped, suggestions, history and completion
+    # metadata exactly as they were before that step was answered.
+    #
+    # Display steps passed with #advance in between are stepped over, since
+    # there is nothing on them to change. Steps elided by skip_if or by a
+    # prefilled answer were never presented and so are never returned to.
+    #
+    # The undone answer stays available through #previous_answer, so a
+    # renderer can re-ask the question with it pre-filled.
+    #
+    # Rebuilding the earlier state by replaying answers is not equivalent: a
+    # Proc default or a prefill! suggestion does not re-derive. So #answer,
+    # #skip and #advance each push a #to_state snapshot before they mutate,
+    # and this restores one.
+    #
+    # The snapshot stack is deliberately excluded from #to_state: it is
+    # session-local undo, not flow state, and persisting it would nest every
+    # earlier state inside each saved one. An engine rebuilt by .from_state
+    # therefore starts with nothing to go back to.
+    #
+    # @example Re-ask the previous question with its answer filled in
+    #   engine.answer("married")
+    #   engine.back                              # => true
+    #   engine.previous_answer(:filing_status)   # => "married"
+    #
+    # @return [Boolean] true when the engine moved back; false, with nothing
+    #   changed, when no collecting step has been answered yet
+    def back
+      index = @snapshots.rindex { |state| collecting_step?(state[:current_step_id]) }
+      return false unless index
+
+      @rewound_answers.merge!(@answers)
+      load_state(@snapshots[index])
+      @snapshots.slice!(index..)
+      true
+    end
+
+    # Whether #back would move the engine.
+    #
+    # @return [Boolean]
+    def can_back?
+      @snapshots.any? { |state| collecting_step?(state[:current_step_id]) }
+    end
+
+    # The answer to pre-fill when a step is asked again after #back: the
+    # step's current answer when it has one, otherwise the last answer #back
+    # took away from it.
+    #
+    # @param step_id [Symbol, String] step id
+    # @return [Object, nil] nil when the step was never answered
+    def previous_answer(step_id)
+      sym = step_id.to_sym
+      @answers.fetch(sym) { @rewound_answers[sym] }
+    end
+
+    # The current step's default as a concrete value, resolved exactly as
+    # #skip records it: a Proc default is called with the answers so far.
+    # Renderers pre-fill with it; a headless run under `yes` answers with it.
+    #
+    # @return [Object, nil] nil when the flow is finished or the step has no default
+    def current_default
+      return nil if finished?
+
+      resolve_default(current_step)
+    end
+
     # Whether the user explicitly skipped the given step via #skip.
     #
     # @param step_id [Symbol, String] step id
@@ -311,17 +384,55 @@ module Inquirex
     def restore_state(definition, state, validator)
       @definition = definition
       @validator = validator
+      @after_completion_hooks = []
+      @completion_hook_errors = []
+      @snapshots = []
+      @rewound_answers = {}
+      load_state(state)
+    end
+
+    # Loads the flow-state fields of a #to_state hash, leaving the session
+    # (validator, hooks, the #back stack) alone. Shared by .from_state and
+    # #back so the two cannot disagree about what a state contains.
+    #
+    # @param state [Hash] symbol-keyed state, as #to_state returns it
+    # @return [void]
+    def load_state(state)
       @current_step_id = state[:current_step_id]
       @answers = state[:answers] || {}
       @history = state[:history] || []
       @totals = state[:totals] || init_totals
       @completion_metadata = CompletionMetadata.from_h(state[:completion_metadata])
-      @after_completion_hooks = []
-      @completion_hook_errors = []
       @suggestions = state[:suggestions] || {}
       @skipped = state[:skipped] || []
     end
 
+    # Records the state before #answer, #skip or #advance changes it. The
+    # copy is deep: those methods mutate the answers, totals, history,
+    # suggestions and skipped collections in place.
+    #
+    # @return [void]
+    def push_snapshot
+      @snapshots << deep_copy(to_state)
+    end
+
+    # @param value [Object]
+    # @return [Object] a copy sharing no Hash, Array or String with +value+
+    def deep_copy(value)
+      case value
+      when Hash   then value.to_h { |k, v| [k, deep_copy(v)] }
+      when Array  then value.map { |v| deep_copy(v) }
+      when String then value.dup
+      else value
+      end
+    end
+
+    # @param step_id [Symbol, nil]
+    # @return [Boolean] whether +step_id+ names a step that collects an answer
+    def collecting_step?(step_id)
+      !step_id.nil? && @definition.step(step_id).collecting?
+    end
+
     # Whether +step_id+ names a multi-select step in the definition. Unknown
     # ids (e.g. an extract schema field that matches no step) are not.
     #

data/lib/inquirex/headless.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Runs a flow to the end from a hash of preset answers, with no terminal,
+  # no prompt and no LLM: the driver behind `inquirex-tty run --answers` and
+  # `--yes`, and the way to run a flow in tests and CI.
+  #
+  # Answers reach the engine through Engine#answer and Engine#skip only,
+  # never Engine#prefill!. prefill! records a multi-select as a suggestion
+  # that no skip_if rule can see, so a flow whose multi-select is gated on
+  # its own answer would stop on that question with nobody to answer it.
+  #
+  # Step by step:
+  #
+  # - a display step advances silently;
+  # - a step present in +answers+ is answered with that value, as given (an
+  #   LLM step included: the value stands in for the adapter's output, and
+  #   nothing is splatted into other answers);
+  # - otherwise, with +yes+, a step with a default is answered with it (a
+  #   Proc default resolved against the answers so far);
+  # - otherwise an optional step is skipped, recording its default as
+  #   Engine#skip does;
+  # - otherwise, with +yes+, a required LLM step is answered with nil;
+  # - otherwise the run stops with MissingAnswer naming the step.
+  #
+  # No LLM adapter is ever called: core has none, and a run under +yes+ is
+  # meant to be offline and repeatable.
+  #
+  # @example Run a flow from an answers file's contents
+  #   results = Inquirex::Headless.new(definition, answers: { filing_status: "single" }, yes: true).call
+  #   results[:answers]     # => { filing_status: "single", dependents: 0, ... }
+  #   results[:path_taken]  # => [:filing_status, :dependents, :done]
+  class Headless
+    # Raised when a step needs an answer that neither +answers+ nor (with
+    # +yes+) a default supplies.
+    class MissingAnswer < Errors::EngineError
+      # @return [Symbol] the step left without an answer
+      attr_reader :step_id
+
+      # @param step_id [Symbol]
+      def initialize(step_id)
+        @step_id = step_id
+        super("No answer for required step #{step_id.inspect}: give one in the answers, or a default with yes")
+      end
+    end
+
+    # The engine the run drives. Register Engine#after_completion hooks on it
+    # before #call to attach completion metadata.
+    #
+    # @return [Engine]
+    attr_reader :engine
+
+    # @param definition [Definition] the flow to run
+    # @param answers [Hash{Symbol, String => Object}] preset answers by step id;
+    #   string keys, as JSON and YAML produce them, are accepted
+    # @param yes [Boolean] take each unanswered step's default
+    def initialize(definition, answers: {}, yes: false)
+      @engine = Engine.new(definition)
+      @answers = answers.to_h { |step_id, value| [step_id.to_sym, value] }
+      @yes = yes
+    end
+
+    # Drives the engine until the flow finishes.
+    #
+    # @return [Hash] +:path_taken+ (step ids, in order), +:answers+
+    #   (Engine#answers_with_metadata) and +:steps_completed+. A caller adds
+    #   whatever it knows that the engine does not, such as the flow file or a
+    #   completion time.
+    # @raise [MissingAnswer] when a step can be given no answer
+    # @raise [Errors::ValidationError] when the validator rejects an answer
+    def call
+      take(@engine.current_step) until @engine.finished?
+      results
+    end
+
+    private
+
+    # Moves the engine past one step.
+    #
+    # @param node [Node]
+    # @return [void]
+    def take(node)
+      return @engine.advance if node.display?
+      return @engine.answer(@answers[node.id]) if @answers.key?(node.id)
+
+      # Only under yes: resolving a Proc default runs host code.
+      default = @yes ? @engine.current_default : nil
+      return @engine.answer(default) unless default.nil?
+      return @engine.skip unless node.required?
+      return @engine.answer(nil) if @yes && llm_step?(node)
+
+      raise MissingAnswer, node.id
+    end
+
+    # LLM steps come from inquirex-llm, which core does not load, so they are
+    # recognised by the predicate their node class answers.
+    #
+    # @param node [Node]
+    # @return [Boolean]
+    def llm_step?(node) = node.respond_to?(:llm_verb?) && node.llm_verb?
+
+    # @return [Hash]
+    def results
+      {
+        path_taken:      @engine.history,
+        answers:         @engine.answers_with_metadata,
+        steps_completed: @engine.history.length
+      }
+    end
+  end
+end

data/lib/inquirex/version.rb

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

data/lib/inquirex.rb

@@ -49,6 +49,7 @@ require_relative "inquirex/safe_source"
 # Engine
 require_relative "inquirex/engine/state_serializer"
 require_relative "inquirex/engine"
+require_relative "inquirex/headless"
 
 # Graph utilities
 require_relative "inquirex/graph/mermaid_exporter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
   - Konstantin Gredeskoul
@@ -25,6 +25,30 @@ dependencies:
           - ~>
           - !ruby/object:Gem::Version
             version: "0.6"
+  - !ruby/object:Gem::Dependency
+    name: prism
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "1.7"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "2"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "1.7"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "2"
 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, no third-party dependencies, thread-safe immutable definitions."
 email:
   - kigster@gmail.com
@@ -50,6 +74,7 @@ files:
   - lib/inquirex/errors.rb
   - lib/inquirex/evaluator.rb
   - lib/inquirex/graph/mermaid_exporter.rb
+  - lib/inquirex/headless.rb
   - lib/inquirex/node.rb
   - lib/inquirex/rules/all.rb
   - lib/inquirex/rules/any.rb