inquirex 0.7.0 → 0.9.4

data/lib/inquirex/dsl/flow_builder.rb

@@ -16,28 +16,24 @@ module Inquirex
         @nodes = {}
         @meta = {}
         @accumulators = {}
-        @actions = []
-        @allowed_domains = []
-      end
-
-      # Declares the domains outbound effects (webhook) may send answers to.
-      # Conventionally the first declaration in a definition, so the flow's
-      # egress surface is auditable at a glance. "example.com" matches that
-      # host exactly; "*.example.com" matches its subdomains.
-      #
-      # @param domains [Array<String>]
-      def allowed_domains(*domains)
-        @allowed_domains.concat(domains.flatten)
+        @send_emails = []
       end
 
       # Declares a named running total the flow accumulates into as answers come in.
       # The `:price` accumulator is the common lead-qualification use case; others
       # (e.g. :complexity, :credit_score) work identically.
       #
-      # @param name [Symbol] e.g. :price
+      # A `:text` accumulator is filled by the engine rather than by
+      # `accumulate` declarations: it collects everything the user was shown
+      # and every answer they gave, which is what an LLM `summarize` step
+      # reads. See {Accumulator}.
+      #
+      # @param name [Symbol] e.g. :price, :transcript
       # @param type [Symbol] one of Node::TYPES (default :currency-ish: :decimal)
-      # @param default [Numeric] starting value (default: 0)
-      def accumulator(name, type: :decimal, default: 0)
+      # @param default [Numeric, String, nil] starting value; nil (the default)
+      #   takes the type's own zero, so a :text accumulator starts at "" and
+      #   every other kind starts at 0
+      def accumulator(name, type: :decimal, default: nil)
         sym = name.to_sym
         @accumulators[sym] = Accumulator.new(name: sym, type:, default:)
       end
@@ -116,33 +112,45 @@ module Inquirex
         add_step(id, :confirm, &)
       end
 
-      # Declares a named post-completion action: effects (send_email, run, ...)
-      # executed server-side after the flow finishes, with the collected
-      # answers. Runs in declaration order; gate with a serializable rule via
-      # the if: option.
+      # Declares an email the host application builds and delivers after the
+      # flow finishes, from the collected answers. Declarations run in order;
+      # gate with a serializable rule via the if: option. This is the only
+      # completion declaration the core DSL carries — richer post-completion
+      # behavior belongs to the host application.
+      #
+      # @example Receipt sent only when the visitor left an email address
+      #   send_email if: not_empty(:email) do
+      #     to      "{{email}}"
+      #     from    "forms@agentica.group"
+      #     subject "Thanks {{name}} — we got your inquiry"
+      #     markdown_text <<~TEXT
+      #       Hi {{name}},
       #
-      # @example Email the collected answers when business income was selected
-      #   action :notify_sales, if: Rules::Contains.new(:income_types, "Business") do
-      #     send_email to: "sales@example.com",
-      #                subject: "New lead: {{name}}",
-      #                html: "{{answers_summary}}"
+      #       We received your answers and will reply within one business day.
+      #
+      #       {{answers_summary}}
+      #     TEXT
       #   end
       #
-      # @param id [Symbol] action identifier
-      # @param opts [Hash] only if: is recognized — a Rules::Base gate
-      # @yield block evaluated in ActionBuilder (send_email, run, ...)
-      def action(id, **opts, &block)
+      # @param opts [Hash] if: takes a Rules::Base gate; any remaining keys are
+      #   SendEmail fields (to:, subject:, text:, ...) for the inline form
+      # @yield block evaluated in SendEmailBuilder (to, from, subject, ...);
+      #   block values override same-named inline keys
+      # @return [void]
+      # @raise [Errors::DefinitionError] on unknown fields or missing to:/subject:/body
+      def send_email(**opts, &block)
         rule = opts.delete(:if)
-        raise Errors::DefinitionError, "Unknown action options: #{opts.keys.inspect}" unless opts.empty?
-
-        sym = id.to_sym
-        if @actions.any? { |a| a.id == sym }
-          raise Errors::DefinitionError, "Duplicate action id: #{sym.inspect}"
+        params = opts
+        if block
+          builder = SendEmailBuilder.new
+          builder.instance_eval(&block)
+          params = params.merge(builder.params)
+        end
+        begin
+          @send_emails << SendEmail.new(**params, rule:)
+        rescue ArgumentError => e
+          raise Errors::DefinitionError, "send_email: #{e.message}"
         end
-
-        builder = ActionBuilder.new
-        builder.instance_eval(&block) if block
-        @actions << builder.build(sym, rule:)
       end
 
       # Produces the frozen Definition.
@@ -154,14 +162,13 @@ module Inquirex
         raise Errors::DefinitionError, "No steps defined" if @nodes.empty?
 
         Definition.new(
-          start_step_id:   @start_step_id,
-          nodes:           @nodes,
-          id:              @flow_id,
-          version:         @flow_version,
-          meta:            @meta,
-          accumulators:    @accumulators,
-          actions:         @actions,
-          allowed_domains: @allowed_domains
+          start_step_id: @start_step_id,
+          nodes:         @nodes,
+          id:            @flow_id,
+          version:       @flow_version,
+          meta:          @meta,
+          accumulators:  @accumulators,
+          send_emails:   @send_emails
         )
       end
 

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/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

@@ -86,6 +86,35 @@ module Inquirex
       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)

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