inquirex 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a4701c7b2bb8ccf5a9da4a5a25e93be1cc4544371f2d9c1f48c478e04a9af75
-  data.tar.gz: 3192f545c283e0cfedf7eadec341f02d7984c0551ee1454714b51eb7fb1db250
+  metadata.gz: fe9f05cd41bfb91eb6ebf5c75a4a1f8a7323e761516fa4ba303d1df1ad539c9e
+  data.tar.gz: bfc9557af719b4eb03ca651c84d72d9c3d3d7f477763422dbce679caa4c80b2f
 SHA512:
-  metadata.gz: 66b1f3c05ad85be1bc8b70f05b669b540cc116b0f9a985393e7715614fa98a0974c631e7ca5cb709b29a2c000fd4f4eb535fea81c14959572e63be817069117d
-  data.tar.gz: 957265be4973894ff8d2a5b219a89c68196a880c63179e103c652fafd67cdb71fe1809a68db23e2b403ff72e1d4fc78810694c03bf58cb45aed02dcf13051443
+  metadata.gz: 8bf741953e3400e1ce9ac050e5ee3bfc521c52db204d2c2d21c45ae5e80b0cdedff71c6fef3f82c86c5a80c98c2ce85aa0c4f52925047ec8d31c188284fec9fd
+  data.tar.gz: 1bf3e9c4fc15c4c4eb1e2f6efdc2fb41a50c39eb52f18f46bb2012f1377da58ab7e55f27f3300185095d2e0039e383d4c572ccc1b3e0239b8e2e65528bcb31f5

data/README.md

@@ -311,7 +311,9 @@ Inquirex.define id: "depreciation-help" do
   accumulator :transcript, type: :text
   start :intro
 
-  say(:intro) { text "Depreciation spreads an asset's cost over its useful life."; transition to: :asset_kind }
+  say(:intro) do 
+    text "Depreciation spreads an asset's cost over its useful life."; transition to: :asset_kind
+	end
   ask :asset_kind do
     type :enum
     question "What kind of asset?"
@@ -471,6 +473,7 @@ Behavior:
 - Use `finished?` to detect completion
 - Use `total(:price)` / `totals` to read running totals
 - Use `to_state` / `.from_state` for persistence/resume (totals included)
+- Use `back` to undo the last answer or skip and re-ask that question (see [Going Back](#going-back))
 - Use `prefill!(hash)` to merge externally-supplied answers into the state, e.g. fields extracted by an LLM from a free-text answer (see [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil` and empty values are ignored so they don't spuriously satisfy `not_empty` rules. The engine auto-advances past any newly-skippable step.
 
 ```ruby
@@ -552,6 +555,57 @@ On the wire, step JSON carries `"required": false` (omitted when true, like othe
 > [!NOTE]
 > **`skip_if` is not the same thing.** A `skip_if` rule is *flow logic*: the definition elides the step from the path automatically, no default kicks in, and the step is **not** added to `engine.skipped` — it was never presented, so the user cannot have declined it. `Engine#skip` is a *user action* on a question that was presented. See [`docs/design/required-and-skip.md`](docs/design/required-and-skip.md) for the full design.
 
+## Going Back
+
+`Engine#back` undoes the last `answer` or `skip` and returns the engine to that question, so a renderer can offer a **Back** control. Every `answer`, `skip` and `advance` pushes a snapshot of the full state before it mutates, and `back` restores the most recent snapshot taken at a *collecting* step — display steps (`say`, `header`, `btw`, `warning`) are stepped over, since there is nothing to re-answer there.
+
+```ruby
+engine.answer("married")                # :filing_status -> :dependents
+engine.answer(2)                        # :dependents    -> :state
+engine.back                             # => true; back at :dependents
+engine.previous_answer(:dependents)     # => 2, pre-fill the input with it
+engine.back                             # => true; back at :filing_status
+engine.back                             # => false; nothing to undo
+```
+
+What `back` restores is the snapshot, not a replay: answers, running totals (including `:text` transcripts), `skipped`, prefilled suggestions, history and completion metadata all come back exactly as they were. Replaying answers would not be equivalent — a Proc `default` or a `prefill!` suggestion does not re-derive.
+
+- `engine.can_back?` says whether `back` would move; use it to decide whether to show the control at all.
+- `engine.previous_answer(step_id)` returns the step's current answer if it has one, otherwise the last answer `back` took away from it — so the question can be re-asked with the old value filled in.
+- `engine.current_default` resolves the current step's default as `skip` would (a Proc default is called with the answers so far), for pre-filling.
+- `back` keeps the validator and any `after_completion` hooks registered on the engine.
+
+> [!NOTE]
+> The undo stack is **session-local** and is deliberately left out of `to_state`. An engine rebuilt with `.from_state` starts with nothing to go back to; persisting the stack would nest every earlier state inside each saved one.
+
+## Headless Runs
+
+`Inquirex::Headless` runs a flow to the end from a hash of preset answers — no terminal, no prompt, no LLM adapter. It is the driver behind `inquirex-tty run --answers` and `--yes`, and the simplest way to exercise a flow in tests and CI.
+
+```ruby
+run = Inquirex::Headless.new(
+  definition,
+  answers: { filing_status: "single", state: "CA" },  # string keys (from JSON/YAML) are fine too
+  yes: true                               # take each unanswered step's default
+)
+results = run.call
+
+results[:path_taken]       # => [:filing_status, :dependents, :state, :done]
+results[:answers]          # => answers_with_metadata (includes :skipped, :completion_metadata)
+results[:steps_completed]  # => 4 (steps visited, display steps included)
+```
+
+For each step, in order:
+
+1. A display step advances silently.
+1. A step present in `answers:` is answered with that value verbatim — an LLM step included: the value stands in for the adapter's output and is **not** splatted into other answers, so put downstream answers in the hash directly.
+1. Otherwise, with `yes: true`, a step with a `default` is answered with it (Proc defaults are resolved against the answers so far).
+1. Otherwise an optional step is skipped, recording its default exactly as `Engine#skip` does.
+1. Otherwise, with `yes: true`, a required LLM step with no default is answered with `nil`.
+1. Otherwise the run stops with `Inquirex::Headless::MissingAnswer` (an `Errors::EngineError` carrying `#step_id`).
+
+Answers reach the engine only through `answer` and `skip`, never `prefill!` — a prefilled multi-select is a *suggestion* that no `skip_if` rule can see, which would leave such a step waiting for an answer nobody is there to give. Register `after_completion` hooks on `run.engine` before `call` to attach completion metadata.
+
 ## Completion Metadata
 
 When a flow finishes, the engine guarantees a `CompletionMetadata` — an OpenStruct describing how the answers were collected. Only `engine` and `engine_version` are required members; rendering front-ends attach richer environment details from an `after_completion` hook:
@@ -735,6 +789,7 @@ Common exceptions under `Inquirex::Errors`:
 - `ValidationError`
 - `NonCollectingStepError`
 - `RequiredStepError`
+- `Headless::MissingAnswer`
 - `SendEmailError`
 
 ## Development

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