inquirex 0.8.0 → 0.9.5

data/lib/inquirex/dsl/send_email_builder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Collects the fields of a `send_email` block. Every setter is an explicit
+    # builder method — the block form mirrors the step builders (`type`,
+    # `question`, ...) rather than a keyword-argument hash:
+    #
+    #   send_email if: not_empty(:email) do
+    #     to      "{{email}}"
+    #     from    "forms@agentica.group"
+    #     subject "Thanks {{name}}"
+    #     markdown_text <<~TEXT
+    #       Hi {{name}}, we got your answers:
+    #
+    #       {{answers_summary}}
+    #     TEXT
+    #   end
+    class SendEmailBuilder
+      # @return [Hash{Symbol => Object}] collected SendEmail constructor params
+      attr_reader :params
+
+      def initialize
+        @params = {}
+      end
+
+      # @param value [String] recipient template ({{field}} placeholders allowed)
+      # @return [void]
+      def to(value)
+        @params[:to] = value
+      end
+
+      # @param value [String] sender template
+      # @return [void]
+      def from(value)
+        @params[:from] = value
+      end
+
+      # @param value [String] carbon-copy template
+      # @return [void]
+      def cc(value)
+        @params[:cc] = value
+      end
+
+      # @param value [String] blind-carbon-copy template
+      # @return [void]
+      def bcc(value)
+        @params[:bcc] = value
+      end
+
+      # @param value [String] reply-to template
+      # @return [void]
+      def reply_to(value)
+        @params[:reply_to] = value
+      end
+
+      # @param value [String] subject template
+      # @return [void]
+      def subject(value)
+        @params[:subject] = value
+      end
+
+      # @param value [Hash] extra headers (values support {{field}})
+      # @return [void]
+      def headers(value)
+        @params[:headers] = value
+      end
+
+      # @param value [String, Hash] plain-text body template or { file: "path" }
+      # @return [void]
+      def text(value)
+        @params[:text] = value
+      end
+
+      # @param value [String, Hash] Markdown body template or { file: "path" }
+      # @return [void]
+      def markdown_text(value)
+        @params[:markdown_text] = value
+      end
+
+      # @param value [String, Hash] HTML body template or { file: "path" }
+      # @return [void]
+      def html(value)
+        @params[:html] = value
+      end
+    end
+  end
+end

data/lib/inquirex/dsl/step_builder.rb

@@ -18,6 +18,7 @@ module Inquirex
         @skip_if = nil
         @default = nil
         @required = true
+        @requiredness = nil
         @compute = nil
         @widget_hints = {}
         @accumulations = []
@@ -138,8 +139,34 @@ module Inquirex
       #   end
       #
       # @param value [Boolean] false to make the step skippable
+      # @raise [Errors::DefinitionError] if the step also declares `optional` to the contrary
       def required(value = true)
-        @required = value
+        assign_requiredness(:required, value ? true : false)
+      end
+
+      # Declares this step skippable — the inverse of {#required}, and the form
+      # most flows want. Since steps are required by default, `required true` is
+      # a no-op and the keyword only ever appears as `required false`; `optional`
+      # says the same thing without the double negative.
+      #
+      # Sugar only: both spellings serialize to the single wire field
+      # `"required": false`, so a definition round-trips identically however it
+      # was authored and no consumer has to learn a second key.
+      #
+      # @example Equivalent to `required false`, and easier to read
+      #   ask :dependents do
+      #     type :integer
+      #     question "How many dependents?"
+      #     optional
+      #     default 0
+      #     transition to: :done
+      #   end
+      #
+      # @param value [Boolean] true (the default) to make the step skippable
+      # @return [void]
+      # @raise [Errors::DefinitionError] if the step also declares `required` to the contrary
+      def optional(value = true)
+        assign_requiredness(:optional, value ? false : true)
       end
 
       # Registers a compute block: auto-calculates a value from answers, not shown to user.
@@ -150,6 +177,51 @@ module Inquirex
         @compute = block
       end
 
+      # Declares the inclusive lower bound of a numeric step.
+      #
+      # Only meaningful for `:integer`, `:decimal` and `:currency`; declaring it
+      # on any other type raises at build time rather than being ignored.
+      #
+      # @example A headcount that cannot be negative
+      #   ask :employees do
+      #     type :integer
+      #     question "How many employees?"
+      #     min 0
+      #     max 500
+      #     transition to: :done
+      #   end
+      #
+      # @param value [Numeric] inclusive lower bound
+      # @return [void]
+      def min(value)
+        @min = value
+      end
+
+      # Declares the inclusive upper bound of a numeric step.
+      #
+      # @param value [Numeric] inclusive upper bound
+      # @return [void]
+      # @see #min
+      def max(value)
+        @max = value
+      end
+
+      # Declares the increment a numeric step's stepper arrows move by.
+      #
+      # Defaults, when unset, to 1 for `:integer` and 0.01 for `:decimal` and
+      # `:currency` — the renderer applies that, not this builder, so an unset
+      # value stays absent from the wire format.
+      #
+      # Spelled `step_size` rather than `step` because a step *is* the unit of
+      # a flow; `steps.employees.step` would read as a nested flow step.
+      #
+      # @param value [Numeric] stepper increment
+      # @return [void]
+      # @see #min
+      def step_size(value)
+        @step_size = value
+      end
+
       # Builds the Node for the given step id.
       #
       # @param id [Symbol]
@@ -166,6 +238,9 @@ module Inquirex
           skip_if:       @skip_if,
           default:       @default,
           required:      @required,
+          min:           @min,
+          max:           @max,
+          step_size:     @step_size,
           widget_hints:  resolve_widget_hints,
           accumulations: @accumulations
         )
@@ -173,6 +248,26 @@ module Inquirex
 
       private
 
+      # Records requiredness from either spelling, rejecting a step that says
+      # both things at once. `required false` alongside `optional` agrees and is
+      # allowed — harmlessly redundant — but `required` with `optional` is a
+      # contradiction, and silently letting the last call win would hide it.
+      #
+      # @param keyword [Symbol] :required or :optional, for the error message
+      # @param value [Boolean] the resulting requiredness
+      # @return [void]
+      # @raise [Errors::DefinitionError] on contradictory declarations
+      def assign_requiredness(keyword, value)
+        if !@requiredness.nil? && @requiredness != value
+          raise Errors::DefinitionError,
+            "Step declares both required and optional with conflicting values " \
+            "(#{keyword} would make it #{value ? "required" : "optional"}); use one"
+        end
+
+        @requiredness = value
+        @required = value
+      end
+
       def pick_accumulator_shape(lookup:, per_selection:, per_unit:, flat:)
         provided = { lookup:, per_selection:, per_unit:, flat: }.compact
         if provided.size != 1

data/lib/inquirex/engine.rb

@@ -74,6 +74,23 @@ module Inquirex
       @totals[name.to_sym] || 0
     end
 
+    # The running narrative of a `:text` accumulator — everything the user was
+    # shown and everything they answered, in the order it happened. This is
+    # what an LLM `summarize` step reads.
+    #
+    # @param name [Symbol] text accumulator name (e.g. :transcript)
+    # @return [String] empty when nothing has been captured yet
+    def text(name)
+      @totals[name.to_sym].to_s
+    end
+
+    # Every text accumulator's running narrative, keyed by name.
+    #
+    # @return [Hash{Symbol => String}]
+    def texts
+      text_accumulator_names.to_h { |name| [name, text(name)] }
+    end
+
     # @return [Node, nil] current step node, or nil if flow is finished
     def current_step
       return nil if finished?
@@ -101,9 +118,11 @@ module Inquirex
       result = @validator.validate(current_step, value)
       raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
+      node = current_step
       @answers[@current_step_id] = value
       @suggestions.delete(@current_step_id)
-      apply_accumulations(current_step, value)
+      apply_accumulations(node, value)
+      capture_transcript(Transcript.answer_entry(node, value))
       advance_step
     end
 
@@ -113,6 +132,8 @@ module Inquirex
     def advance
       raise Errors::AlreadyFinishedError, "Flow is already finished" if finished?
 
+      node = current_step
+      capture_transcript(Transcript.display_entry(node)) if node.display?
       advance_step
     end
 
@@ -152,6 +173,7 @@ module Inquirex
       end
       @skipped << @current_step_id unless @skipped.include?(@current_step_id)
       @suggestions.delete(@current_step_id)
+      capture_transcript(Transcript.skipped_entry(node))
       advance_step
     end
 
@@ -165,14 +187,21 @@ module Inquirex
 
     # Merges a hash of { step_id => value } into the top-level answers without
     # clobbering answers the user has already provided. Used by LLM clarify
-    # steps to populate downstream answers from free-text extraction so that
-    # `skip_if not_empty(:id)` rules on later steps will fire.
+    # steps to populate downstream answers from free-text extraction; a
+    # prefilled question is treated as answered and is never asked again.
     #
     # Nil/empty values in the hash are ignored so that "unknown" LLM outputs
     # don't spuriously satisfy `not_empty` rules.
     #
-    # If the engine's current step becomes skippable as a result of the prefill,
-    # it auto-advances past it.
+    # Values for steps with options (enum / multi_enum) are canonicalized via
+    # Node#resolve_option — matching is against the option's form VALUE, with
+    # a case-insensitive fallback and a label fallback ("US citizen or
+    # permanent resident" resolves to "us_person"). A value that matches
+    # neither value nor label is dropped, so junk never enters the answers.
+    #
+    # Prefilled answers contribute to accumulators exactly like typed ones,
+    # and if the engine's current step becomes skippable as a result of the
+    # prefill, it auto-advances past it.
     #
     # @param hash [Hash] answers keyed by step id
     # @return [Hash] the updated answers
@@ -185,13 +214,9 @@ module Inquirex
 
         sym = key.to_sym
         if multi_select_step?(sym)
-          # Multi-select extraction is a hint, not a fact: the user may have
-          # more selections in mind than the text revealed. Record it as a
-          # suggestion so renderers pre-check the choices while the question
-          # is still asked; skip_if rules see no answer and do not fire.
-          @suggestions[sym] = Array(value) unless @answers.key?(sym)
+          prefill_suggestion(sym, value)
         else
-          @answers[sym] = value unless @answers.key?(sym)
+          prefill_answer(sym, value)
         end
       end
       skip_if_needed unless finished?
@@ -319,6 +344,30 @@ module Inquirex
       end
     end
 
+    # @return [Array<Symbol>] names of the flow's :text accumulators
+    def text_accumulator_names
+      @definition.accumulators.filter_map { |name, acc| name if acc.text? }
+    end
+
+    # Appends one narrative entry to every text accumulator the flow declares.
+    #
+    # Called only from #answer, #skip, and #advance — the three points at
+    # which the user has actually seen or done something. Steps the engine
+    # elides on its own (skip_if, or a question already answered by an
+    # extraction) pass through #advance_step instead and are correctly absent
+    # from the narrative.
+    #
+    # @param entry [String, nil] formatted entry, or nil for nothing to record
+    # @return [void]
+    def capture_transcript(entry)
+      return if entry.nil? || entry.empty?
+
+      text_accumulator_names.each do |name|
+        existing = @totals[name].to_s
+        @totals[name] = existing.empty? ? entry : "#{existing}\n\n#{entry}"
+      end
+    end
+
     # The step's default as a concrete value: a Proc default (server-side only,
     # stripped from JSON) is called with the answers collected so far, exactly
     # as a renderer pre-filling the field would resolve it.
@@ -367,12 +416,44 @@ module Inquirex
       @completion_metadata = CompletionMetadata.new(engine: "inquirex", engine_version: VERSION)
     end
 
-    # Auto-skips the current step if its skip_if rule is satisfied.
+    # Multi-select extraction is a hint, not a fact: the user may have more
+    # selections in mind than the text revealed. Record it as a suggestion so
+    # renderers pre-check the choices while the question is still asked;
+    # skip_if rules see no answer and do not fire. Each entry is
+    # canonicalized against the step's option values; unmatchable entries
+    # are dropped, and an all-junk extraction records no suggestion.
+    def prefill_suggestion(sym, value)
+      return if @answers.key?(sym)
+
+      node = @definition.step(sym)
+      resolved = Array(value).filter_map { |entry| node.resolve_option(entry) }
+      @suggestions[sym] = resolved unless resolved.empty?
+    end
+
+    # Single-value extraction is deterministic: the canonicalized value is
+    # recorded as the answer (feeding accumulators like a typed answer), and
+    # the question will be auto-skipped when reached. Unknown keys — schema
+    # fields with no matching step, e.g. a confidence score — are stored
+    # verbatim so rules can still read them.
+    def prefill_answer(sym, value)
+      return if @answers.key?(sym)
+
+      node = @definition.step_ids.include?(sym) ? @definition.step(sym) : nil
+      resolved = node ? node.resolve_option(value) : value
+      return if resolved.nil?
+
+      @answers[sym] = resolved
+      apply_accumulations(node, resolved) if node
+    end
+
+    # Auto-skips the current step when its skip_if rule is satisfied, or when
+    # it is a collecting step whose answer already exists (prefilled by an
+    # LLM extraction) — an answered question is never asked again.
     def skip_if_needed
       return if finished?
 
       node = @definition.step(@current_step_id)
-      return unless node.skip?(@answers)
+      return unless node.skip?(@answers) || (node.collecting? && @answers.key?(@current_step_id))
 
       advance_step
     end

data/lib/inquirex/errors.rb

@@ -32,8 +32,25 @@ module Inquirex
     # Raised when serializing or deserializing a Definition to/from JSON fails.
     class SerializationError < Error; end
 
-    # Raised when a post-completion action cannot execute structurally,
-    # e.g. send_email is used without the mail gem installed.
-    class ActionError < Error; end
+    # Raised when DSL source contains anything outside the flow-DSL allowlist,
+    # i.e. when it is not safe to `eval`. See Inquirex::SafeSource.
+    #
+    # Subclasses DefinitionError on purpose: hosts that already rescue that
+    # class and render the message keep working, and a rejected payload reads
+    # as "invalid DSL" rather than as a crash.
+    class UnsafeSourceError < DefinitionError
+      # @return [Array<String>] every violation found, most useful first
+      attr_reader :violations
+
+      # @param violations [Array<String>, String] human-readable violation messages
+      def initialize(violations)
+        @violations = Array(violations)
+        super("DSL rejected: #{@violations.join("; ")}")
+      end
+    end
+
+    # Raised when a SendEmail cannot build its message structurally,
+    # e.g. SendEmail#to_mail is called without the mail gem installed.
+    class SendEmailError < Error; end
   end
 end

data/lib/inquirex/node.rb

@@ -40,6 +40,12 @@ module Inquirex
       enum multi_enum date email phone
     ].freeze
 
+    # Types for which {#min}, {#max} and {#step_size} carry meaning. Declaring
+    # a bound on anything else is a definition error rather than a silent
+    # no-op — a bounded `:string` almost always means the author picked the
+    # wrong type, and failing loudly is cheaper than shipping it.
+    BOUNDED_TYPES = %i[integer decimal currency].freeze
+
     attr_reader :id,
       :verb,
       :type,
@@ -51,6 +57,9 @@ module Inquirex
       :skip_if,
       :default,
       :required,
+      :min,
+      :max,
+      :step_size,
       :widget_hints,
       :accumulations
 
@@ -64,6 +73,9 @@ module Inquirex
       skip_if: nil,
       default: nil,
       required: true,
+      min: nil,
+      max: nil,
+      step_size: nil,
       widget_hints: nil,
       accumulations: [])
       @id = id.to_sym
@@ -75,17 +87,81 @@ module Inquirex
       @skip_if = skip_if
       @default = default
       @required = required ? true : false
+      @min = coerce_bound(min)
+      @max = coerce_bound(max)
+      @step_size = coerce_bound(step_size)
       @widget_hints = widget_hints&.freeze
       @accumulations = accumulations.freeze
       extract_options(options)
+      validate_bounds!
       freeze
     end
 
+    # Whether this step declares any numeric bound at all.
+    #
+    # @return [Boolean]
+    def bounded?
+      !@min.nil? || !@max.nil?
+    end
+
+    # Pulls a number inside this step's declared bounds.
+    #
+    # The wire format carries `min`/`max` so a renderer can *present* them, but
+    # an HTML number input does not stop a visitor typing past them and an LLM
+    # extraction has no notion of them at all. Every path that stores an answer
+    # for a bounded step goes through here, so the bound holds regardless of
+    # which client produced the value.
+    #
+    # @example
+    #   node.clamp(900)  # => 10, for a step declaring `max 10`
+    #
+    # @param value [Object] candidate answer
+    # @return [Object] the clamped Numeric, or the value unchanged when it is
+    #   not numeric or the step declares no bounds
+    def clamp(value)
+      return value unless bounded?
+      return value unless value.is_a?(Numeric)
+
+      clamped = value
+      clamped = @min if @min && clamped < @min
+      clamped = @max if @max && clamped > @max
+      clamped
+    end
+
     # @return [Boolean] true if this step collects input from the user
     def collecting?
       COLLECTING_VERBS.include?(@verb)
     end
 
+    # Canonicalizes a raw value against this step's options: an exact value
+    # match wins, then a case-insensitive value match, then a case-insensitive
+    # label match — LLM extractions and humans often answer with the friendly
+    # label ("US citizen or permanent resident") when the form value is the
+    # canonical key ("us_person"). Matching is always resolved TO the form
+    # value, never the label. Steps without options return the value
+    # unchanged; an unmatchable value returns nil rather than polluting
+    # answers with junk that would satisfy not_empty rules.
+    #
+    # @example
+    #   node.options                                             # => ["us_person", "resident"]
+    #   node.resolve_option("us_person")                         # => "us_person"
+    #   node.resolve_option("US_PERSON")                         # => "us_person"
+    #   node.resolve_option("US citizen or permanent resident")  # => "us_person"
+    #   node.resolve_option("alien overlord")                    # => nil
+    #
+    # @param raw [Object] candidate value (String, Symbol, ...)
+    # @return [String, Object, nil] the canonical option value; the raw value
+    #   unchanged for steps without options; nil when nothing matches
+    def resolve_option(raw)
+      return raw if @options.nil? || @options.empty?
+      return nil if raw.nil?
+
+      candidate = raw.to_s
+      @options.find { |value| value == candidate } ||
+        @options.find { |value| value.casecmp?(candidate) } ||
+        @option_labels&.find { |_value, label| label.casecmp?(candidate) }&.first
+    end
+
     # @return [Boolean] true if this step only displays content (no input)
     def display?
       DISPLAY_VERBS.include?(@verb)
@@ -150,6 +226,9 @@ module Inquirex
         hash["skip_if"] = @skip_if.to_h if @skip_if
         hash["default"] = @default unless @default.nil? || @default.is_a?(Proc)
         hash["required"] = false unless @required
+        hash["min"] = @min unless @min.nil?
+        hash["max"] = @max unless @max.nil?
+        hash["step_size"] = @step_size unless @step_size.nil?
       elsif @text
         hash["text"] = @text
       end
@@ -186,6 +265,9 @@ module Inquirex
       default = hash["default"] || hash[:default]
       # Fetch chain (not ||) so an explicit false survives; absent key means required.
       required = hash.fetch("required") { hash.fetch(:required, true) }
+      min = hash["min"] || hash[:min]
+      max = hash["max"] || hash[:max]
+      step_size = hash["step_size"] || hash[:step_size]
       widget_data = hash["widget"] || hash[:widget]
       accumulate_data = hash["accumulate"] || hash[:accumulate]
 
@@ -206,6 +288,9 @@ module Inquirex
         skip_if:,
         default:,
         required:,
+        min:,
+        max:,
+        step_size:,
         widget_hints:,
         accumulations:
       )
@@ -213,6 +298,29 @@ module Inquirex
 
     private
 
+    # Numeric bounds arrive as Integers from Ruby DSL and as either Integer or
+    # Float from parsed JSON. Anything else — a String "10", a Symbol — is a
+    # definition error, not something to coerce quietly into 0.
+    def coerce_bound(value)
+      return nil if value.nil?
+      raise Errors::DefinitionError, "step #{@id}: numeric bound must be a number, got #{value.inspect}" unless value.is_a?(Numeric)
+
+      value
+    end
+
+    def validate_bounds!
+      return if @min.nil? && @max.nil? && @step_size.nil?
+
+      if @type && !BOUNDED_TYPES.include?(@type)
+        raise Errors::DefinitionError,
+          "step #{@id}: min/max/step_size only apply to #{BOUNDED_TYPES.join(", ")} steps, not #{@type}"
+      end
+
+      return unless @min && @max && @min > @max
+
+      raise Errors::DefinitionError, "step #{@id}: min (#{@min}) is greater than max (#{@max})"
+    end
+
     def extract_options(raw)
       case raw
       when Hash

data/lib/inquirex/safe_source/call_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module SafeSource
+    # The shape a single allowlisted DSL call may take, built by
+    # {Vocabulary.allow} and consumed by {Validator}. Its three members:
+    #
+    # - `positional` — accepted positional arguments. An Array names each slot's
+    #   kind in order (`[:symbol]`); `{ repeat: kind, min: n }` accepts any
+    #   number of arguments of one kind; `{ optional: kind }` accepts zero or one.
+    # - `keywords` — `nil` when the call takes no keyword arguments, or a Hash
+    #   mapping each accepted keyword to its value kind. The key
+    #   {Vocabulary::ANY_OTHER} sets the kind for every keyword not named
+    #   explicitly, and is only legitimate when the real method takes `**rest`.
+    # - `block` — `:forbidden`; the name of the nested scope whose vocabulary
+    #   the block's statements are validated against; or `{ optional: scope }`
+    #   for a call that accepts that block but does not require it, mirroring
+    #   the `positional` spelling. `send_email` is the optional case: it takes
+    #   its fields either as keywords or from a block.
+    #
+    # Value kinds are `:literal`, `:string`, `:symbol`, `:type_name` and `:rule`.
+    #
+    # @example The spec behind `transition to: :next, if_rule: equals(:a, 1)`
+    #   CallSpec.new(positional: [],
+    #     keywords: { to: :symbol, if_rule: :rule, requires_server: :literal },
+    #     block:    :forbidden)
+    CallSpec = Data.define(:positional, :keywords, :block) do
+      # The scope this call's block opens, with `{ optional: scope }`
+      # unwrapped, or nil when the call takes no block at all. Callers that
+      # care whether the block is required read {#block} itself.
+      #
+      # @return [Symbol, nil]
+      def block_scope
+        case block
+        when :forbidden then nil
+        when Hash       then block[:optional]
+        else block
+        end
+      end
+    end
+  end
+end