inquirex-llm 0.8.0 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e08a0d70d91af1bc1cd099d6b1cc32398e3e83e20a49245fcead8e7dfd7b809b
-  data.tar.gz: 91e2e04cd12c5a75978d91c77b06d0f6b3ba0c4827d2a0eea7401151e6ba4eb0
+  metadata.gz: 2d7bb4e511826270c246b50b51b9305bfa5d117bf00a93a4cb64d6def3904697
+  data.tar.gz: 929c58c5fcb08cfd4210594d1cf34d1bb47b873e91f7b23e5215c6bca576b045
 SHA512:
-  metadata.gz: 90e8b76887633ecd3841a01e2e2de0b59ed178e4458191d1bc2ebeb96928c9f8c8bc9c36da6eb3dddc9e2a59081f41eca94d050166330f5264d96c20a18819e7
-  data.tar.gz: 4abdf58f828cbbe125cd8f00297cacc0d04a9ebd46f07b5f2c22f4e9c8fb26d98a29f85a48531dd3f73f0c0c3fe08341e862d2059deb6475062027768d87474f
+  metadata.gz: 0a9f47a1bb791ac80cee430b5e97009a456d3312b76bd66dcc784c28aeb463a06e0e99a6b47811519f4f62c91ec8c6f6d443b7e937d96b7c8c187036aaa44812
+  data.tar.gz: a0475eb9b50579a4873bd3dc5cc034b0ca17135bf5d590614121570c8153c1586f34bf7d4bbacc77acd7cf187a41a36148cb31d086bc6f700d5e8ab24b764e6b

data/README.md

@@ -4,7 +4,7 @@
 
 LLM integration verbs for the [Inquirex](https://github.com/inquirex/inquirex) questionnaire engine.
 
-Extends the core DSL with a server-side `extract` verb (alias: `clarify`) that turns free-text answers into structured data via LLM processing. Ships with a pluggable adapter interface and a `NullAdapter` for testing. (`describe`, `summarize`, and `detour` are temporarily parked.)
+Extends the core DSL with two server-side verbs: `extract` (alias: `clarify`), which turns free-text answers into structured data, and `summarize`, which closes a flow with a prose summary of the whole session. Ships with a pluggable adapter interface and a `NullAdapter` for testing. (`describe` and `detour` are temporarily parked.)
 
 `inquirex` is a pure Ruby, declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys.
 
@@ -14,8 +14,8 @@ Extends the core DSL with a server-side `extract` verb (alias: `clarify`) that t
 >
 > - [`inquirex`](https://github.com/inquirex/inquirex)
 > - [`inquirex-llm`](https://github.com/inquirex/inquirex-llm)
-> - [`inquirex-tty`](https://github.com/inquirex/inquirex-)
-> - [`inquirex-js`](https://github.com/inquirex/inquirex-js) (`npmjs` module [`@kigster/inquirex-js`](https://www.npmjs.com/package/@kigster/inquirex-js))
+> - [`inquirex-tty`](https://github.com/inquirex/inquirex-tty)
+> - [`inquirex-widget`](https://github.com/inquirex/inquirex-widget) (`npmjs` module [`inquirex-widget`](https://www.npmjs.com/package/inquirex-widget), formerly `@kigster/inquirex-js`)
 >
 > For a presentation about these gems and what they do please watch the [RubySF presentation](https://www.youtube.com/watch?v=iaoKW7Ap3_M&t=1s) and you can also [view the slides from the presentation](https://reinvent.one/images/talks/pdfs/2026.inquirex.pdf).
 >
@@ -60,6 +60,18 @@ end
 
 All core verbs (`ask`, `say`, `header`, `btw`, `warning`, `confirm`) and widget hints work alongside LLM verbs in the same `Inquirex.define` block.
 
+### Loading stored flows
+
+Since inquirex 0.7.0, `Inquirex.load_dsl` validates source against a **default-deny** allowlist before evaluating it — a word nobody declared is a violation, not an oversight. Requiring this gem registers its own vocabulary (`extract`, `clarify`, `summarize`, and the methods legal inside their blocks), so a flow stored in a database or authored in a visual builder loads normally:
+
+```ruby
+Inquirex.load_dsl(customer.flow_dsl)   # validates, then evaluates
+```
+
+`fallback` is the one deliberate exception: it takes a Ruby block, which is exactly what static validation cannot vet, so it is excluded from the allowlist rather than permitted. Flows that need it must be loaded from your own source with `unsafe: true`.
+
+Registration is skipped on inquirex versions predating the allowlist, so the gem still works against them.
+
 ## Currently Supported LLM Verbs
 
 ### `extract` (alias: `clarify`)
@@ -78,12 +90,61 @@ extract :business_extracted do
 end
 ```
 
+### `summarize`
+
+Closes a flow with a multi-paragraph prose summary of the whole session, written for the user to read and keep.
+
+```ruby
+Inquirex.define id: "depreciation-help" do
+  start :intro
+
+  say(:intro) { text "Depreciation spreads an asset's cost over its useful life."; transition to: :asset }
+  ask(:asset) { type :enum; question "What kind of asset?"; options vehicle: "A vehicle", building: "A building" }
+
+  summarize :wrap_up do
+    temperature 0.4
+  end
+end
+```
+
+Two things make it different from every other verb.
+
+**It reads the transcript, not the answers.** The core gem's [text accumulators](https://github.com/inquirex/inquirex#text-accumulators-the-session-transcript) record everything the user was shown and every answer they gave. That is what `summarize` is given. It matters because a flow that mostly *explains* things — a help widget, an explainer — collects almost no answers, so a summary built from the answers hash would have nothing to say. Declaring `summarize` adds a `:transcript` accumulator automatically if the flow declares no text accumulator of its own.
+
+**The gem owns the prompt.** `Inquirex::LLM::Prompts::SUMMARIZE` is a constant, and adapters read it from there rather than from `node.prompt`. A flow author who could replace it could make the summary assert things the session never established, over a signature that still reads as the application's own words — so `prompt` is rejected at definition time rather than ignored at runtime, and a hand-forged or tampered node cannot substitute its own instructions either.
+
+The prompt constrains the model to what the transcript establishes, and to the markdown subset a renderer can lay out and print: headings, lists, blockquotes, emphasis, inline code, and fenced code blocks.
+
+#### What it refuses, and why
+
+| Rejected                                    | Because                                      |
+| ------------------------------------------- | -------------------------------------------- |
+| `prompt`                                    | its prompt is owned by the gem               |
+| `schema`                                    | it returns prose, not fields                 |
+| `from` / `from_all`                         | it always reads the whole session transcript |
+| a transition, or any step declared after it | it must be the last step in the flow         |
+| a second `summarize` step                   | a flow may close with only one               |
+
+Each raises `Errors::DefinitionError` naming the reason.
+
+`temperature`, `model`, and `max_tokens` remain available: they change how the summary is generated, not what it is allowed to say.
+
+#### Calling it
+
+`summarize` uses its own adapter method, because nothing about the call resembles an extraction — the prompt is the gem's, the input is the transcript, and the result is a markdown `String` rather than a schema-shaped `Hash`:
+
+```ruby
+adapter = Inquirex::LLM::AnthropicAdapter.new(api_key: ENV["ANTHROPIC_API_KEY"])
+markdown = adapter.summarize(engine.current_step, engine.text(:transcript))
+```
+
+An adapter that implements only `#call` keeps working for `extract` and raises `NotImplementedError` the first time a flow asks it to summarize — loudly, rather than returning something that looks like a summary and is not. An empty transcript raises `Errors::AdapterError` rather than asking a model to invent one.
+
+The [inquirex-widget](https://github.com/inquirex/inquirex-widget) renders the result with **Close** and **Print** buttons; markdown is sanitized against a strict element allowlist before it reaches the page.
+
 ## Schema: Question References (preferred)
 
-Most extract schemas exist to pre-fill questions asked later in the same flow. Declaring
-those fields twice — once in the schema, once in the question — invites drift, and worse:
-a hand-typed `income_types: :multi_enum` gives the LLM no idea which values are legal, so
-its answers won't match the question's options.
+Most extract schemas exist to pre-fill questions asked later in the same flow. Declaring those fields twice — once in the schema, once in the question — invites drift, and worse: a hand-typed `income_types: :multi_enum` gives the LLM no idea which values are legal, so its answers won't match the question's options.
 
 Instead, pass the schema as a list of question ids:
 
@@ -104,16 +165,9 @@ end
 # ...
 ```
 
-Each symbol is resolved against the flow at definition time — references may point
-**forward** to questions defined after the extract step. The gem looks up the question's
-declared type, and for `:enum` / `:multi_enum` questions folds the exhaustive list of
-allowed option values into the JSON schema sent to the LLM. The adapters then instruct
-the model to answer using only those values, so extracted answers always match the
-downstream question's options (and `Engine#prefill!` can skip the question).
+Each symbol is resolved against the flow at definition time — references may point **forward** to questions defined after the extract step. The gem looks up the question's declared type, and for `:enum` / `:multi_enum` questions folds the exhaustive list of allowed option values into the JSON schema sent to the LLM. The adapters then instruct the model to answer using only those values, so extracted answers always match the downstream question's options (and `Engine#prefill!` can skip the question).
 
-A symbol that matches no `ask`/`confirm` step in the flow fails validation with
-`Inquirex::LLM::Errors::DefinitionError` — as do references to display-only steps and
-other LLM steps.
+A symbol that matches no `ask`/`confirm` step in the flow fails validation with `Inquirex::LLM::Errors::DefinitionError` — as do references to display-only steps and other LLM steps.
 
 Both forms compose. Use keywords for output fields that have no corresponding question:
 
@@ -123,9 +177,7 @@ schema :filing_status, :income_types, confidence: :decimal
 
 ### `prompt :auto`
 
-When the schema is built from question references, the schema already tells the LLM the
-field names, types, and allowed values — the main thing a hand-written prompt still adds
-is the questions' own wording. `prompt :auto` generates exactly that at definition time:
+When the schema is built from question references, the schema already tells the LLM the field names, types, and allowed values — the main thing a hand-written prompt still adds is the questions' own wording. `prompt :auto` generates exactly that at definition time:
 
 ```ruby
 extract :extracted do
@@ -136,31 +188,27 @@ extract :extracted do
 end
 ```
 
-The generated prompt enumerates each referenced question's text ("- filing_status: What
-is your filing status for 2025?" …), lists explicit keyword fields by name and type, and
-instructs the model to leave unsupported fields empty. Generation happens at build time,
-so the wire format and adapters always see a concrete prompt string — `:auto` never
-leaves the DSL. It requires at least one question reference; with only explicit
-`key: :type` fields there is no question wording to generate from, and validation fails.
+The generated prompt enumerates each referenced question's text ("- filing_status: What is your filing status for 2025?" …), lists explicit keyword fields by name and type, and instructs the model to leave unsupported fields empty. Generation happens at build time, so the wire format and adapters always see a concrete prompt string — `:auto` never leaves the DSL. It requires at least one question reference; with only explicit `key: :type` fields there is no question wording to generate from, and validation fails.
 
-Write the prompt by hand when you need domain framing the questions don't carry
-("for tax filing purposes", "map S-Corp to s_corp") — an explicit prompt always wins.
+Write the prompt by hand when you need domain framing the questions don't carry ("for tax filing purposes", "map S-Corp to s_corp") — an explicit prompt always wins.
 
 ## DSL Methods (inside LLM verb blocks)
 
-| Method                          | Purpose                                              | Required                      |
-| ------------------------------- | ---------------------------------------------------- | ----------------------------- |
-| `prompt "..."` / `prompt :auto` | LLM prompt template, or generated from question refs | Always                        |
-| `schema :question_id, ...`      | Fields resolved from questions (types + options)     | `extract` (this or keywords)  |
-| `schema key: :type, ...`        | Explicit field => type pairs                         | `extract` (this or refs)      |
-| `from :step_id`                 | Source step(s) whose answers feed the LLM            | `extract` (or use `from_all`) |
-| `from_all`                      | Pass all collected answers to the LLM                | Alternative to `from`         |
-| `model :claude_sonnet`          | Optional model hint for the adapter                  | No                            |
-| `temperature 0.3`               | Optional sampling temperature                        | No                            |
-| `max_tokens 1024`               | Optional max output tokens                           | No                            |
-| `fallback { \|answers\| ... }`  | Server-side fallback (stripped from JSON)            | No                            |
-| `transition to: :step`          | Conditional transition (same as core)                | No                            |
-| `skip_if rule`                  | Skip step when condition is true                     | No                            |
+| Method                          | Purpose                                              | Required                                                   |
+| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| `prompt "..."` / `prompt :auto` | LLM prompt template, or generated from question refs | `extract`; **rejected** on `summarize`                     |
+| `schema :question_id, ...`      | Fields resolved from questions (types + options)     | `extract` (this or keywords); **rejected** on `summarize`  |
+| `schema key: :type, ...`        | Explicit field => type pairs                         | `extract` (this or refs); **rejected** on `summarize`      |
+| `from :step_id`                 | Source step(s) whose answers feed the LLM            | `extract` (or use `from_all`); **rejected** on `summarize` |
+| `from_all`                      | Pass all collected answers to the LLM                | Alternative to `from`; **rejected** on `summarize`         |
+| `model :claude_sonnet`          | Optional model hint for the adapter                  | No                                                         |
+| `temperature 0.3`               | Optional sampling temperature                        | No                                                         |
+| `max_tokens 1024`               | Optional max output tokens                           | No                                                         |
+| `fallback { \|answers\| ... }`  | Server-side fallback (stripped from JSON)            | No                                                         |
+| `transition to: :step`          | Conditional transition (same as core)                | No; **rejected** on `summarize`                            |
+| `skip_if rule`                  | Skip step when condition is true                     | No                                                         |
+
+`summarize` rejects the content-shaping methods rather than ignoring them — see [`summarize`](#summarize) for each refusal and its reason.
 
 ## Engine Integration
 
@@ -307,10 +355,7 @@ LLM steps serialize with `"requires_server": true` so the JS widget knows to rou
 }
 ```
 
-Unconstrained fields serialize as a plain type string; fields resolved from `:enum` /
-`:multi_enum` questions serialize as `{ "type": ..., "values": [...] }` so any consumer
-(the JS widget, a server adapter) sees the full contract. Fallback procs are stripped
-from JSON (server-side only).
+Unconstrained fields serialize as a plain type string; fields resolved from `:enum` / `:multi_enum` questions serialize as `{ "type": ..., "values": [...] }` so any consumer (the JS widget, a server adapter) sees the full contract. Fallback procs are stripped from JSON (server-side only).
 
 ## Custom Adapter
 
@@ -349,18 +394,6 @@ describe :business_narrative do
 end
 ```
 
-### `summarize`
-
-Produce a summary of all or selected answers. Use `from_all` to pass everything, or `from` to select specific steps.
-
-```ruby
-summarize :intake_summary do
-  from_all
-  prompt "Summarize this client's tax situation."
-  transition to: :review
-end
-```
-
 ### `detour` (parked)
 
 Dynamically generate follow-up questions based on an answer. The server adapter handles presenting the generated questions and collecting responses. Requires `from`, `prompt`, and `schema`.
@@ -374,8 +407,6 @@ detour :followup do
 end
 ```
 
-## 
-
 ## Development
 
 ```bash

data/lib/inquirex/llm/adapter.rb

@@ -35,6 +35,38 @@ module Inquirex
         raise NotImplementedError, "#{self.class}#call must be implemented"
       end
 
+      # Produces the closing prose summary for a `summarize` step.
+      #
+      # Separate from {#call} because nothing about it is the same: the prompt
+      # is the gem's rather than the node's, the input is the session
+      # transcript rather than selected answers, and the result is markdown
+      # rather than a schema-shaped Hash. Keeping it apart also means an
+      # existing custom adapter that only implements #call keeps working for
+      # `extract` and fails loudly — rather than subtly — if a flow starts
+      # asking it to summarise.
+      #
+      # @param node [LLM::Node] the summarize step
+      # @param transcript [String] everything the user was shown and answered
+      # @param answers [Hash] collected answers, for adapters that want them
+      # @return [String] markdown summary
+      # @raise [Errors::AdapterError] if the LLM call fails
+      def summarize(node, transcript, answers = {})
+        raise NotImplementedError, "#{self.class}#summarize must be implemented"
+      end
+
+      # The user-side prompt for a summarize call: the transcript, and nothing
+      # else that could compete with it for the model's attention.
+      #
+      # @param transcript [String]
+      # @return [String]
+      # @raise [Errors::AdapterError] when there is nothing to summarise
+      def summary_input(transcript)
+        text = transcript.to_s.strip
+        raise Errors::AdapterError, "Cannot summarize an empty transcript" if text.empty?
+
+        "Here is the session transcript.\n\n#{text}"
+      end
+
       # Gathers the source answer data that feeds the LLM prompt.
       #
       # @param node [LLM::Node]
@@ -65,8 +97,51 @@ module Inquirex
           "LLM output for #{node.id.inspect} missing fields: #{missing.join(", ")}"
       end
 
+      # Canonicalizes LLM output against the schema's value constraints — the
+      # regression guard for "the model answered with a label or a case
+      # variant". Every value-constrained field is matched against the
+      # allowed form values: an exact match passes through, a
+      # case-insensitive match is rewritten to the canonical value, and a
+      # value outside the list becomes nil (enum) or is dropped from the
+      # array (multi_enum) — "unknown, will ask" instead of junk that
+      # prefills the wrong option downstream. Unconstrained fields are
+      # untouched.
+      #
+      # @param node [LLM::Node]
+      # @param output [Hash, Object] parsed LLM response
+      # @return [Hash, Object] output with constrained fields canonicalized
+      def normalize_output(node, output)
+        schema = node.respond_to?(:schema) ? node.schema : nil
+        return output unless schema && output.is_a?(Hash)
+
+        output.to_h do |key, raw|
+          values = schema.values_for(key)
+          next [key, raw] unless values
+
+          if schema.fields[key.to_sym] == :multi_enum
+            [key, Array(raw).filter_map { |entry| canonical_value(values, entry) }]
+          else
+            [key, canonical_value(values, raw)]
+          end
+        end
+      end
+
       protected
 
+      # The canonical form value for a raw LLM answer, or nil when the answer
+      # is outside the allowed list (after trimming and case-folding).
+      #
+      # @param values [Array<String>] allowed form values
+      # @param raw [Object] one LLM-provided value
+      # @return [String, nil]
+      def canonical_value(values, raw)
+        return nil if raw.nil?
+
+        candidate = raw.to_s.strip
+        values.find { |value| value == candidate } ||
+          values.find { |value| value.casecmp?(candidate) }
+      end
+
       # The schema as a JSON contract for the system prompt: enum-constrained
       # fields render as { "type": ..., "values": [...] } so the model knows
       # the exhaustive list of allowed answers.

data/lib/inquirex/llm/anthropic_adapter.rb

@@ -29,6 +29,12 @@ module Inquirex
       DEFAULT_MODEL = "claude-sonnet-4-20250514"
       DEFAULT_MAX_TOKENS = 2048
 
+      # Summaries want a little more room than an extraction (prose, not a
+      # handful of fields) and a little more warmth than one (0.2 produces
+      # summaries that read like a database dump).
+      DEFAULT_SUMMARY_MAX_TOKENS = 4096
+      DEFAULT_SUMMARY_TEMPERATURE = 0.4
+
       # Maps Inquirex short model symbols to concrete Anthropic model ids.
       MODEL_MAP = {
         claude_sonnet: "claude-sonnet-4-20250514",
@@ -65,11 +71,34 @@ module Inquirex
           max_tokens:  max_tokens
         )
 
-        result = parse_response(response)
+        result = normalize_output(node, parse_response(response))
         validate_output!(node, result)
         result
       end
 
+      # Generates the closing summary for a `summarize` step.
+      #
+      # The system prompt is {Prompts::SUMMARIZE} — the node's own prompt is
+      # that same constant, but reading it from the constant means a node
+      # forged by hand or deserialized from a tampered definition still cannot
+      # substitute its own instructions.
+      #
+      # @param node [Inquirex::LLM::Node] the summarize step
+      # @param transcript [String] the session transcript
+      # @param answers [Hash] unused; accepted for interface symmetry
+      # @return [String] markdown summary
+      # @raise [Errors::AdapterError] on API / parse failures
+      def summarize(node, transcript, _answers = {})
+        response = call_api(
+          model:       resolve_model(node),
+          system:      Prompts::SUMMARIZE,
+          user:        summary_input(transcript),
+          temperature: node.respond_to?(:temperature) ? (node.temperature || DEFAULT_SUMMARY_TEMPERATURE) : DEFAULT_SUMMARY_TEMPERATURE,
+          max_tokens:  node.respond_to?(:max_tokens) ? (node.max_tokens || DEFAULT_SUMMARY_MAX_TOKENS) : DEFAULT_SUMMARY_MAX_TOKENS
+        )
+        parse_text_response(response)
+      end
+
       private
 
       def resolve_model(node)
@@ -147,12 +176,34 @@ module Inquirex
         JSON.parse(response.body)
       end
 
-      def parse_response(api_response)
+      # The response's text content, with the model's habitual wrapping fence
+      # removed. Unlike {#parse_response} it stays a String: a summary is
+      # markdown for a human, not JSON for the engine.
+      #
+      # @param api_response [Hash]
+      # @return [String]
+      # @raise [Errors::AdapterError] when the response carries no text, or
+      #   the model returned nothing usable
+      def parse_text_response(api_response)
+        text = response_text(api_response)
+        text = text.gsub(/\A```(?:markdown|md)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
+        raise Errors::AdapterError, "Anthropic returned an empty summary" if text.empty?
+
+        text
+      end
+
+      # @return [String] the first text block's content
+      # @raise [Errors::AdapterError] when there is none
+      def response_text(api_response)
         content    = api_response["content"]
         text_block = content.is_a?(Array) ? content.find { |c| c["type"] == "text" } : nil
         raise Errors::AdapterError, "No text content in Anthropic response" unless text_block
 
-        raw_text = text_block["text"].to_s.strip
+        text_block["text"].to_s.strip
+      end
+
+      def parse_response(api_response)
+        raw_text = response_text(api_response)
         raw_text = raw_text.gsub(/\A```(?:json)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
 
         parsed = JSON.parse(raw_text, symbolize_names: true)

data/lib/inquirex/llm/dsl/flow_builder.rb

@@ -15,6 +15,10 @@ module Inquirex
       # so that schema question references can resolve forward to questions
       # defined after the LLM step.
       module FlowBuilderExtension
+        # Accumulator added when a flow declares `summarize` without declaring
+        # anywhere for the narrative to accumulate.
+        TRANSCRIPT_ACCUMULATOR = :transcript
+
         # Defines an LLM extraction step: takes free-text input and produces
         # structured data matching the declared schema.
         #
@@ -33,13 +37,27 @@ module Inquirex
         #   add_llm_step(id, :describe, &)
         # end
 
-        # # Defines an LLM summarization step: takes all or selected answers and
-        # # produces a textual summary.
-        # #
-        # # @param id [Symbol] step id
-        # def summarize(id, &)
-        #   add_llm_step(id, :summarize, &)
-        # end
+        # Closes the flow with a prose summary of the whole session.
+        #
+        # Takes no prompt (the gem owns it — see {Prompts::SUMMARIZE}), no
+        # schema, and no `from`: its input is always the session transcript,
+        # and its output is markdown for the user to read, keep, and print.
+        # It must be the last step declared in the flow, and a flow may
+        # declare only one.
+        #
+        # Declaring it also guarantees the flow has somewhere to summarise
+        # *from*: if no `:text` accumulator was declared, a `:transcript` one
+        # is added automatically.
+        #
+        # @example
+        #   summarize :wrap_up do
+        #     temperature 0.4
+        #   end
+        #
+        # @param id [Symbol] step id
+        def summarize(id, &)
+          add_llm_step(id, :summarize, &)
+        end
 
         # # Defines an LLM detour step: based on an answer, dynamically generates
         # # follow-up questions. The server adapter handles presenting the generated
@@ -53,12 +71,67 @@ module Inquirex
         # Builds any deferred LLM steps (now that the full node map exists),
         # then produces the frozen Definition via the core builder.
         def build
+          validate_summarize_placement!
+          ensure_transcript_accumulator!
           resolve_llm_steps!
           super
         end
 
         private
 
+        # @return [Array<Symbol>] ids of the flow's summarize steps, in
+        #   declaration order
+        def summarize_step_ids
+          @nodes.filter_map { |id, entry| id if summarize_entry?(entry) }
+        end
+
+        # True for a parked LlmStepBuilder or an already-built node whose verb
+        # is :summarize.
+        def summarize_entry?(entry)
+          entry.respond_to?(:verb) ? entry.verb.to_sym == :summarize : entry.instance_variable_get(:@verb) == :summarize
+        end
+
+        # `summarize` closes the flow, so it has to be the last step declared
+        # and there can only be one. Checked here rather than in the step
+        # builder because only the flow builder knows the declaration order —
+        # the step builder sees one step at a time.
+        #
+        # @raise [Errors::DefinitionError]
+        def validate_summarize_placement!
+          ids = summarize_step_ids
+          return if ids.empty?
+
+          if ids.length > 1
+            raise Errors::DefinitionError,
+              "flow declares #{ids.length} summarize steps (#{ids.map(&:inspect).join(", ")}) — " \
+              "a flow may close with only one"
+          end
+
+          last_id = @nodes.keys.last
+          return if ids.first == last_id
+
+          raise Errors::DefinitionError,
+            "summarize step #{ids.first.inspect} is followed by #{last_id.inspect} — " \
+            "summarize must be the last step declared in the flow"
+        end
+
+        # Guarantees a `summarize` flow has a narrative to summarise. A flow
+        # that mostly explains things collects almost no answers, so without a
+        # text accumulator there would be nothing to send the model but an
+        # empty hash.
+        def ensure_transcript_accumulator!
+          return if summarize_step_ids.empty?
+          return if @accumulators.any? { |_, acc| text_accumulator?(acc) }
+
+          accumulator(TRANSCRIPT_ACCUMULATOR, type: :text)
+        end
+
+        # `Accumulator#text?` arrived with text accumulators; fall back to the
+        # type for the older core versions this gem still supports.
+        def text_accumulator?(acc)
+          acc.respond_to?(:text?) ? acc.text? : acc.type.to_sym == :text
+        end
+
         # Evaluates the step block immediately (same as core FlowBuilder#add_step)
         # but parks the builder in the node map instead of building the node.
         # The builder placeholder holds this step's position; #build replaces it.

data/lib/inquirex/llm/dsl/llm_step_builder.rb

@@ -167,7 +167,7 @@ module Inquirex
 
           field_map = resolve_schema_refs(id, nodes).merge(@schema_fields)
           schema_obj = field_map.empty? ? nil : Schema.new(**field_map)
-          prompt_text = @prompt == :auto ? auto_prompt(nodes) : @prompt
+          prompt_text = resolve_prompt(nodes)
 
           LLM::Node.new(
             id:,
@@ -189,6 +189,19 @@ module Inquirex
 
         private
 
+        # The prompt this step will carry on the wire. `summarize` takes the
+        # gem's own text and never the author's; `:auto` is expanded here so
+        # that adapters only ever see a concrete string.
+        #
+        # @param nodes [Hash{Symbol => Inquirex::Node}, nil]
+        # @return [String]
+        def resolve_prompt(nodes)
+          return Prompts::SUMMARIZE if @verb == :summarize
+          return auto_prompt(nodes) if @prompt == :auto
+
+          @prompt
+        end
+
         # Turns question references into full field specs by looking up each
         # referenced step in the flow: its declared type, and for enum-like
         # types the exhaustive list of allowed option values.
@@ -271,6 +284,8 @@ module Inquirex
         end
 
         def validate!(id)
+          return validate_summarize!(id) if @verb == :summarize
+
           raise Errors::DefinitionError, "LLM step #{id.inspect} requires a prompt" if @prompt.nil?
 
           if @prompt == :auto && @schema_refs.empty?
@@ -297,6 +312,39 @@ module Inquirex
           raise Errors::DefinitionError,
             "LLM step #{id.inspect} (#{@verb}) requires `from` or `from_all`"
         end
+
+        # `summarize` is defined by what it refuses. Its prompt is the gem's
+        # ({Prompts::SUMMARIZE}), its input is always the whole session
+        # transcript, its output is prose rather than fields, and it ends the
+        # flow. Every setter below would contradict one of those, so each is
+        # rejected at definition time with the reason rather than ignored at
+        # runtime.
+        #
+        # `temperature`, `model`, and `max_tokens` stay available: they change
+        # how the summary is generated, not what it is allowed to say.
+        def validate_summarize!(id)
+          reject_summarize!(id, "declares a prompt", "its prompt is owned by the gem") unless @prompt.nil?
+
+          unless @schema_fields.empty? && @schema_refs.empty?
+            reject_summarize!(id, "declares a schema", "it returns prose, not fields")
+          end
+
+          unless @from_steps.empty? && !@from_all
+            reject_summarize!(id,
+              "declares `from`/`from_all`",
+              "it always reads the whole session transcript")
+          end
+
+          return if @transitions.empty?
+
+          reject_summarize!(id, "declares a transition", "it must be the last step in the flow")
+        end
+
+        # @raise [Errors::DefinitionError]
+        def reject_summarize!(id, what, why)
+          raise Errors::DefinitionError,
+            "summarize step #{id.inspect} #{what}, which is not allowed — #{why}"
+        end
       end
     end
   end

data/lib/inquirex/llm/node.rb

@@ -8,10 +8,14 @@ module Inquirex
     #
     # LLM verbs:
     #   :extract   — extract structured data from a free-text answer
+    #   :summarize — close the flow with a prose summary of the whole session
     #   # :describe  — generate natural-language text from structured data
-    #   # :summarize — produce a summary of all or selected answers
     #   # :detour    — dynamically generate follow-up questions based on an answer
     #
+    # `summarize` is the one verb whose prompt the gem owns ({Prompts::SUMMARIZE})
+    # and whose answer is markdown prose rather than structured data. It must be
+    # the last step in a flow and carries no schema and no transitions.
+    #
     # All LLM nodes are collecting (they produce answers) and require server
     # round-trips. The frontend shows a "thinking" state while the server processes.
     #
@@ -24,9 +28,13 @@ module Inquirex
     # @attr_reader max_tokens [Integer, nil] optional max output tokens
     # @attr_reader fallback [Proc, nil] server-side fallback (stripped from JSON)
     class Node < Inquirex::Node
-      LLM_VERBS = %i[extract].freeze
+      LLM_VERBS = %i[extract summarize].freeze
       # LLM_VERBS = %i[extract describe summarize detour].freeze
 
+      # Verbs whose result is prose for the user to read, not data for the
+      # engine to store against other steps.
+      NARRATIVE_VERBS = %i[summarize].freeze
+
       attr_reader :prompt,
         :schema,
         :from_steps,
@@ -59,6 +67,13 @@ module Inquirex
       # Whether this is an LLM-powered step requiring server processing.
       def llm_verb? = true
 
+      # Whether this step closes the flow with prose for the user to read.
+      # Narrative steps carry no schema and no transitions.
+      def narrative? = NARRATIVE_VERBS.include?(@verb)
+
+      # Whether this is the `summarize` step.
+      def summarize? = @verb == :summarize
+
       # Serializes to a plain Hash. LLM metadata is nested under "llm".
       # Fallback procs are stripped (server-side only).
       # All transitions are marked requires_server: true.

data/lib/inquirex/llm/null_adapter.rb

@@ -47,6 +47,25 @@ module Inquirex
         end
       end
 
+      # Placeholder summary, in the markdown shape a real summary takes — so a
+      # renderer wired against this adapter exercises its heading, list, and
+      # paragraph handling rather than one unbroken line.
+      #
+      # @param node [LLM::Node] the summarize step
+      # @param transcript [String] the session transcript
+      # @param _answers [Hash] ignored
+      # @return [String] markdown
+      def summarize(node, transcript, _answers = {})
+        <<~MARKDOWN.strip
+          This is a placeholder summary for #{node.id}. No language model was called.
+
+          ## What the session contained
+
+          - A transcript of #{transcript.to_s.strip.length} characters.
+          - Nothing else worth reporting, because this adapter invents nothing.
+        MARKDOWN
+      end
+
       private
 
       def placeholder_for(schema, name, type)

data/lib/inquirex/llm/openai_adapter.rb

@@ -24,6 +24,11 @@ module Inquirex
       DEFAULT_MODEL = "gpt-4o-mini"
       DEFAULT_MAX_TOKENS = 2048
 
+      # Summaries want more room than an extraction (prose, not a handful of
+      # fields) and more warmth than one (0.2 reads like a database dump).
+      DEFAULT_SUMMARY_MAX_TOKENS = 4096
+      DEFAULT_SUMMARY_TEMPERATURE = 0.4
+
       # Maps Inquirex DSL model symbols to concrete OpenAI model ids. Accepts
       # Claude symbols too — we substitute sensible OpenAI equivalents so flow
       # definitions written against Anthropic still run against this adapter.
@@ -66,11 +71,33 @@ module Inquirex
           max_tokens:  max_tokens
         )
 
-        result = parse_response(response)
+        result = normalize_output(node, parse_response(response))
         validate_output!(node, result)
         result
       end
 
+      # Generates the closing summary for a `summarize` step.
+      #
+      # The system prompt is read from {Prompts::SUMMARIZE} rather than from
+      # the node, so a hand-forged or tampered node cannot substitute its own
+      # instructions.
+      #
+      # @param node [Inquirex::LLM::Node] the summarize step
+      # @param transcript [String] the session transcript
+      # @param answers [Hash] unused; accepted for interface symmetry
+      # @return [String] markdown summary
+      # @raise [Errors::AdapterError] on API / parse failures
+      def summarize(node, transcript, _answers = {})
+        response = call_api(
+          model:       resolve_model(node),
+          system:      Prompts::SUMMARIZE,
+          user:        summary_input(transcript),
+          temperature: node.respond_to?(:temperature) ? (node.temperature || DEFAULT_SUMMARY_TEMPERATURE) : DEFAULT_SUMMARY_TEMPERATURE,
+          max_tokens:  node.respond_to?(:max_tokens) ? (node.max_tokens || DEFAULT_SUMMARY_MAX_TOKENS) : DEFAULT_SUMMARY_MAX_TOKENS
+        )
+        parse_text_response(response)
+      end
+
       private
 
       def resolve_model(node)
@@ -152,13 +179,35 @@ module Inquirex
         JSON.parse(response.body)
       end
 
-      def parse_response(api_response)
+      # The response's message content, with the model's habitual wrapping
+      # fence removed. Unlike {#parse_response} it stays a String: a summary
+      # is markdown for a human, not JSON for the engine.
+      #
+      # @param api_response [Hash]
+      # @return [String]
+      # @raise [Errors::AdapterError] when the response carries no content, or
+      #   the model returned nothing usable
+      def parse_text_response(api_response)
+        text = response_text(api_response)
+        text = text.gsub(/\A```(?:markdown|md)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
+        raise Errors::AdapterError, "OpenAI returned an empty summary" if text.empty?
+
+        text
+      end
+
+      # @return [String] the first choice's message content
+      # @raise [Errors::AdapterError] when there is none
+      def response_text(api_response)
         choices = api_response["choices"]
         message = choices.is_a?(Array) ? choices.first&.dig("message") : nil
         raw_text = message&.dig("content")
         raise Errors::AdapterError, "No message content in OpenAI response" unless raw_text
 
-        raw_text = raw_text.to_s.strip
+        raw_text.to_s.strip
+      end
+
+      def parse_response(api_response)
+        raw_text = response_text(api_response)
         raw_text = raw_text.gsub(/\A```(?:json)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
 
         parsed = JSON.parse(raw_text, symbolize_names: true)

data/lib/inquirex/llm/prompts.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    # Prompts the gem owns outright.
+    #
+    # `extract` takes its prompt from the flow author, because only the author
+    # knows what they are extracting. `summarize` does not: its job is fixed,
+    # its input is always the session transcript, and its output has to be
+    # markdown a renderer can lay out and print. A flow author who could
+    # replace this text could make the summary say anything — including things
+    # the session never established — over a signature that still reads as the
+    # application's own summary. So the flow author gets `temperature`, and the
+    # gem keeps the words.
+    module Prompts
+      # System prompt for the `summarize` verb.
+      #
+      # Constrains the model to the transcript it is given (the anti-invention
+      # rule is the load-bearing line — a summary that adds plausible detail is
+      # worse than one that omits it), and to the markdown subset the widget
+      # renders and prints.
+      SUMMARIZE = <<~PROMPT
+        You are writing the closing summary for a completed questionnaire session.
+
+        You will be given a transcript: everything the user was shown, and every
+        question they were asked with the answer they gave, in order.
+
+        Write a well-organised, multi-paragraph summary of that session for the
+        user to read and keep.
+
+        Rules:
+        - Use ONLY what the transcript establishes. Never introduce a fact,
+          figure, name, date, or recommendation that is not in it. If something
+          is unclear or was skipped, say so plainly or leave it out — do not
+          guess, and do not fill gaps with what is usually true.
+        - Address the user directly as "you". Do not refer to "the transcript",
+          "the session", or "the form".
+        - Open with a short paragraph stating what was covered. Then organise
+          the substance under headings. Close with next steps only if the
+          transcript actually indicates any.
+        - Where the session mostly explained things rather than collecting
+          answers, summarise the explanation — that is the substance.
+
+        Format your answer as GitHub-flavoured Markdown, using only:
+        headings (##, ###), paragraphs, bullet and numbered lists, blockquotes,
+        bold and italic, inline code, and fenced code blocks with a language tag.
+        Do not wrap the whole answer in a code fence. Do not include HTML.
+        Do not add a title heading; start with the opening paragraph.
+      PROMPT
+    end
+  end
+end

data/lib/inquirex/llm/safe_source.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    # Teaches {Inquirex::SafeSource}'s allowlist about this gem's verbs.
+    #
+    # Since inquirex 0.7.0, `Inquirex.load_dsl` validates source against
+    # {Inquirex::SafeSource::Vocabulary} before evaluating it, and the
+    # vocabulary is default-deny: a word nobody declared is a violation. Every
+    # word this gem adds to the DSL therefore has to be registered, or a
+    # stored flow using `extract` is rejected as unsafe — not because it is
+    # dangerous, but because the allowlist has never heard of it.
+    #
+    # Registration is guarded because the gem supports inquirex versions
+    # predating SafeSource. On those, there is no allowlist to teach and
+    # nothing to do.
+    module SafeSource
+      # Whether the core gem is new enough to have an allowlist.
+      #
+      # @return [Boolean]
+      def self.available?
+        defined?(Inquirex::SafeSource::Vocabulary) ? true : false
+      end
+
+      # Registers the LLM scope and verbs. Idempotent — `register_scope` and
+      # `allow` both overwrite rather than append, so loading the gem twice is
+      # harmless.
+      #
+      # @return [Boolean] false when the core gem has no allowlist
+      def self.install!
+        return false unless available?
+
+        vocabulary = Inquirex::SafeSource::Vocabulary
+        vocabulary.register_scope(
+          :llm_step,
+          label:      "an LLM step",
+          vocabulary: -> { Inquirex::LLM::DSL::LlmStepBuilder.public_instance_methods(false) }
+        )
+
+        install_verbs!(vocabulary)
+        install_step_words!(vocabulary)
+        true
+      end
+
+      # The flow-level verbs: `extract`, its `clarify` alias, and `summarize`.
+      #
+      # @param vocabulary [Module]
+      # @return [void]
+      def self.install_verbs!(vocabulary)
+        %i[extract clarify summarize].each do |verb|
+          vocabulary.allow(:flow, verb, positional: %i[symbol], block: :llm_step)
+        end
+      end
+
+      # The words legal inside an LLM step block.
+      #
+      # `schema` takes a mix of positional question ids and keyword field
+      # types, so both are declared. `fallback` is excluded outright: it takes
+      # a Ruby block, and a block is exactly the thing static validation
+      # cannot vet.
+      #
+      # @param vocabulary [Module]
+      # @return [void]
+      def self.install_step_words!(vocabulary)
+        v = vocabulary
+        v.allow(:llm_step, :prompt, positional: %i[literal])
+        v.allow(:llm_step,
+          :schema,
+          positional: { repeat: :symbol },
+          keywords:   { Inquirex::SafeSource::Vocabulary::ANY_OTHER => :symbol })
+        v.allow(:llm_step, :from, positional: { repeat: :symbol })
+        v.allow(:llm_step, :from_all, positional: { optional: :literal })
+        v.allow(:llm_step, :model, positional: %i[symbol])
+        v.allow(:llm_step, :temperature, positional: %i[literal])
+        v.allow(:llm_step, :max_tokens, positional: %i[literal])
+        v.allow(:llm_step, :question, positional: %i[string])
+        v.allow(:llm_step, :text, positional: %i[string])
+        v.allow(:llm_step, :skip_if, positional: %i[rule])
+        v.allow(:llm_step,
+          :transition,
+          keywords: Inquirex::SafeSource::Vocabulary::TRANSITION_KEYWORDS)
+        v.exclude(:llm_step, :fallback, "a Ruby block cannot be validated")
+      end
+    end
+  end
+end

data/lib/inquirex/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module LLM
-    VERSION = "0.8.0"
+    VERSION = "0.9.4"
   end
 end

data/lib/inquirex/llm.rb

@@ -5,6 +5,7 @@ require "json"
 
 require_relative "llm/version"
 require_relative "llm/errors"
+require_relative "llm/prompts"
 require_relative "llm/schema"
 require_relative "llm/node"
 require_relative "llm/adapter"
@@ -13,14 +14,15 @@ require_relative "llm/anthropic_adapter"
 require_relative "llm/openai_adapter"
 require_relative "llm/dsl/llm_step_builder"
 require_relative "llm/dsl/flow_builder"
+require_relative "llm/safe_source"
 
 module Inquirex
   # LLM integration layer for Inquirex flows.
   #
   # Extends the core DSL with LLM-powered verbs that run server-side:
   #   - extract   — extract structured data from free-text answers (`clarify` is an alias)
+  #   - summarize — close the flow with a prose summary of the whole session
   #   # - describe  — generate natural-language text from structured data
-  #   # - summarize — produce a summary of all or selected answers
   #   # - detour    — dynamically generate follow-up questions
   #
   # LLM calls never happen on the frontend. Steps are marked `requires_server: true`
@@ -46,3 +48,8 @@ end
 # construction until the whole flow is known, so schema question references
 # can resolve forward to questions defined after the LLM step.
 Inquirex::DSL::FlowBuilder.prepend(Inquirex::LLM::DSL::FlowBuilderExtension)
+
+# Teach SafeSource's default-deny allowlist about the verbs just added, so
+# that `Inquirex.load_dsl` accepts a stored flow using them. A no-op on
+# inquirex versions predating SafeSource.
+Inquirex::LLM::SafeSource.install!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-llm
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.4
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -48,6 +48,8 @@ files:
 - lib/inquirex/llm/node.rb
 - lib/inquirex/llm/null_adapter.rb
 - lib/inquirex/llm/openai_adapter.rb
+- lib/inquirex/llm/prompts.rb
+- lib/inquirex/llm/safe_source.rb
 - lib/inquirex/llm/schema.rb
 - lib/inquirex/llm/version.rb
 homepage: https://github.com/inquirex/inquirex-llm