inquirex-llm 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db7e0d183259c896f2b1b5d9bd6ce1808f3a0c89de415a7129d2da2133a1ea49
-  data.tar.gz: dc3a1659f93182d83972dfccaaacbec820509823c293a97de4ac6df596409701
+  metadata.gz: 00b1d649377bb6ff1281a8fd3af730995b86531e44c930cb3c9a267b73e5efe0
+  data.tar.gz: '0478c2970b4d501ee3b9b2ed4dcdd2d620fbc99c522ac863e3ac772a4f75dce6'
 SHA512:
-  metadata.gz: 6b8e8a8c3069ae95d904e3635d3b4947997e812d678dbf562040ae0647563692edef7364977e20ac2eb972d18d3aaeed88f606a1b05fc2d842ba201ff487b748
-  data.tar.gz: a3d8a7a89d4f22b7c3420ae1b22114895bee402314b6e4d303dfd3702f8afae1aeb87eac9a35e53090279a188b2d838c56759a8d2cecfc31179006f64d0d8fe7
+  metadata.gz: a89a5e3ec65fab4be526a2d8bc730c8bb89bfe9b7945ef900fb987546765c29600219e1959dfb9011a43916658feb56f1f5b70625d3645a26aa75bbbe290ebdb
+  data.tar.gz: b9c05000c0b31721f3c00d425b0e525ef309540335d08c10c5c69ba2a6089fab2bc2d10ce53da141f62f1735a631c993b798ed8a7353c50cfb225b4635d59697

data/README.md

@@ -17,7 +17,7 @@ Extends the core DSL with a server-side `extract` verb (alias: `clarify`) that t
 > - [`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))
 >
-> 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 form the presentation](https://reinvent.one/images/talks/pdfs/2026.inquirex.pdf).
+> 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).
 >
 > Finally, the SaaS application [qualified.at](https://qualified.at) allows users to leverage the ecosystem by creating their own custom lead intake flows and integrating them on their own sites.
 
@@ -78,20 +78,89 @@ extract :business_extracted do
 end
 ```
 
+## 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.
+
+Instead, pass the schema as a list of question ids:
+
+```ruby
+extract :extracted do
+  from :description
+  prompt "Extract the client's filing status, dependents, and income types."
+  schema :filing_status, :dependents, :income_types
+  transition to: :filing_status
+end
+
+ask :filing_status do
+  type :enum
+  question "Filing status?"
+  options({ "single" => "Single", "mfj" => "Married Filing Jointly" })
+  transition to: :dependents
+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).
+
+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:
+
+```ruby
+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:
+
+```ruby
+extract :extracted do
+  from :description
+  prompt :auto
+  schema :filing_status, :dependents, :income_types
+  transition to: :filing_status
+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.
+
+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 "..."`                 | LLM prompt template                       | Always                        |
-| `schema key: :type, ...`       | Expected output structure                 | `extract`                     |
-| `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 | 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                            |
 
 ## Engine Integration
 
@@ -224,7 +293,11 @@ LLM steps serialize with `"requires_server": true` so the JS widget knows to rou
     "schema": {
       "industry": "string",
       "employee_count": "integer",
-      "revenue": "currency"
+      "revenue": "currency",
+      "income_types": {
+        "type": "multi_enum",
+        "values": ["W2", "business", "crypto"]
+      }
     },
     "from_steps": ["business_description"],
     "model": "claude_sonnet",
@@ -234,7 +307,10 @@ LLM steps serialize with `"requires_server": true` so the JS widget knows to rou
 }
 ```
 
-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
 

data/lib/inquirex/llm/adapter.rb

@@ -64,6 +64,45 @@ module Inquirex
         raise Errors::SchemaViolationError,
           "LLM output for #{node.id.inspect} missing fields: #{missing.join(", ")}"
       end
+
+      protected
+
+      # 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.
+      #
+      # @param schema [Schema]
+      # @return [String] pretty-printed JSON
+      def schema_contract_json(schema)
+        JSON.pretty_generate(schema.to_h)
+      end
+
+      # Prompt instruction spelling out how value-constrained fields must be
+      # answered. Empty string when the schema has no constrained fields.
+      #
+      # @param schema [Schema]
+      # @return [String]
+      def values_instruction(schema)
+        constrained = schema.field_names.select { |name| schema.values_for(name) }
+        return "" if constrained.empty?
+
+        "\nFor fields that declare \"values\", you MUST answer using ONLY values from that list — " \
+          "return a single value for \"enum\" fields and an array of selected values for " \
+          "\"multi_enum\" fields. Never invent a value outside the list."
+      end
+
+      # One human-readable line per schema field, used in user prompts:
+      #   income_types (multi_enum: W2 | business | crypto)
+      #   dependents (integer)
+      #
+      # @param schema [Schema]
+      # @return [Array<String>]
+      def field_descriptions(schema)
+        schema.fields.map do |field, type|
+          values = schema.values_for(field)
+          values ? "  #{field} (#{type}: #{values.join(" | ")})" : "  #{field} (#{type})"
+        end
+      end
     end
   end
 end

data/lib/inquirex/llm/anthropic_adapter.rb

@@ -86,9 +86,9 @@ module Inquirex
 
       def schema_instruction(node)
         if node.respond_to?(:schema) && node.schema
-          schema_json = node.schema.fields.transform_values(&:to_s)
           "\n\nYou MUST respond with ONLY a valid JSON object matching this schema:\n" \
-            "#{JSON.pretty_generate(schema_json)}\n\n" \
+            "#{schema_contract_json(node.schema)}\n" \
+            "#{values_instruction(node.schema)}\n\n" \
             "Do not include any text before or after the JSON. No markdown fences. Just the raw JSON object."
         else
           "\n\nRespond with a valid JSON object containing your analysis. " \
@@ -107,7 +107,7 @@ module Inquirex
 
         if node.respond_to?(:schema) && node.schema
           parts << "\nExtract these fields from the source data:"
-          node.schema.fields.each { |field, type| parts << "  #{field} (#{type})" }
+          parts.concat(field_descriptions(node.schema))
         end
 
         if node.respond_to?(:from_all) && node.from_all && all_answers.any?

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

@@ -4,12 +4,16 @@ module Inquirex
   module LLM
     module DSL
       # Mixin that adds LLM verb methods to Inquirex::DSL::FlowBuilder.
-      # Included automatically when `require "inquirex-llm"` is called,
+      # Prepended automatically when `require "inquirex-llm"` is called,
       # so that `Inquirex.define` gains `extract` (and its `clarify` alias)
       # without needing a separate entry point.
       #
       # All core verbs (ask, say, header, btw, warning, confirm) remain
-      # unchanged — LLM verbs are purely additive.
+      # unchanged — LLM verbs are purely additive. The mixin must be
+      # prepended (not included) because it overrides #build: LLM steps are
+      # built lazily at #build time, once every step in the flow is known,
+      # so that schema question references can resolve forward to questions
+      # defined after the LLM step.
       module FlowBuilderExtension
         # Defines an LLM extraction step: takes free-text input and produces
         # structured data matching the declared schema.
@@ -46,13 +50,28 @@ module Inquirex
         #   add_llm_step(id, :detour, &)
         # end
 
+        # Builds any deferred LLM steps (now that the full node map exists),
+        # then produces the frozen Definition via the core builder.
+        def build
+          resolve_llm_steps!
+          super
+        end
+
         private
 
-        # Uses the standard Ruby builder pattern (same as core FlowBuilder#add_step).
+        # 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.
         def add_llm_step(id, verb, &block)
           builder = LlmStepBuilder.new(verb)
           builder.instance_eval(&block) if block
-          @nodes[id.to_sym] = builder.build(id)
+          @nodes[id.to_sym] = builder
+        end
+
+        def resolve_llm_steps!
+          @nodes.each do |id, entry|
+            @nodes[id] = entry.build(id, nodes: @nodes) if entry.is_a?(LlmStepBuilder)
+          end
         end
       end
     end

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

@@ -7,21 +7,30 @@ module Inquirex
       # methods (from, prompt, schema, model, temperature, max_tokens, fallback)
       # while inheriting transition and skip_if from the core StepBuilder.
       #
-      # @example
+      # @example Referencing downstream questions (preferred)
       #   extract :business_extracted do
       #     from :business_description
       #     prompt "Extract structured business info."
-      #     schema industry: :string, employee_count: :integer
+      #     schema :entity_type, :employee_band     # resolved from the ask steps
       #     model :claude_sonnet
       #     temperature 0.2
       #     transition to: :next_step
       #   end
+      #
+      # @example Explicit field types (for fields with no matching question)
+      #   extract :business_extracted do
+      #     from :business_description
+      #     prompt "Extract structured business info."
+      #     schema industry: :string, employee_count: :integer
+      #     transition to: :next_step
+      #   end
       class LlmStepBuilder
         include Inquirex::DSL::RuleHelpers
 
         def initialize(verb)
           @verb = verb.to_sym
           @prompt = nil
+          @schema_refs = []
           @schema_fields = {}
           @from_steps = []
           @from_all = false
@@ -38,16 +47,33 @@ module Inquirex
         # Sets the LLM prompt template. Use {{field_name}} for interpolation
         # placeholders that the adapter resolves at runtime.
         #
-        # @param text [String]
+        # Pass `:auto` to generate the prompt from the schema's question
+        # references at build time: each referenced question's own wording is
+        # enumerated, so the LLM sees what was actually asked. Requires at
+        # least one question reference in the schema.
+        #
+        # @param text [String, :auto]
         def prompt(text)
           @prompt = text
         end
 
-        # Declares the expected output schema. Each key is a field name,
-        # each value is an Inquirex data type symbol.
+        # Declares the expected output schema.
+        #
+        # Positional symbols name questions defined elsewhere in the flow;
+        # each is resolved against that step's declared type, and for
+        # :enum / :multi_enum questions the allowed option values are folded
+        # into the schema sent to the LLM. A symbol that matches no ask/confirm
+        # step in the flow fails validation as invalid DSL.
+        #
+        # Keyword pairs declare explicit field => type mappings, for output
+        # fields that have no corresponding question. Both forms compose:
         #
-        # @param fields [Hash{Symbol => Symbol}]
-        def schema(**fields)
+        #   schema :filing_status, :income_types, confidence: :decimal
+        #
+        # @param question_ids [Array<Symbol>] ids of questions to fill
+        # @param fields [Hash{Symbol => Symbol}] explicit field => type pairs
+        def schema(*question_ids, **fields)
+          @schema_refs.concat(question_ids.flatten.map(&:to_sym))
           @schema_fields.merge!(fields)
         end
 
@@ -126,20 +152,27 @@ module Inquirex
           @text = content
         end
 
-        # Builds the LLM::Node.
+        # Builds the LLM::Node. Question references in the schema are resolved
+        # against the full node map, so the flow builder defers this call until
+        # every step — including ones defined after this one — is known.
         #
         # @param id [Symbol]
+        # @param nodes [Hash{Symbol => Inquirex::Node}, nil] all flow nodes,
+        #   required when the schema references question ids
         # @return [LLM::Node]
-        # @raise [Errors::DefinitionError] if prompt is missing
-        def build(id)
+        # @raise [Errors::DefinitionError] if prompt is missing or a schema
+        #   reference does not resolve to an ask/confirm question
+        def build(id, nodes: nil)
           validate!(id)
 
-          schema_obj = @schema_fields.empty? ? nil : Schema.new(**@schema_fields)
+          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
 
           LLM::Node.new(
             id:,
             verb:        @verb,
-            prompt:      @prompt,
+            prompt:      prompt_text,
             schema:      schema_obj,
             from_steps:  @from_steps,
             from_all:    @from_all,
@@ -156,11 +189,98 @@ module Inquirex
 
         private
 
+        # 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.
+        #
+        # @param id [Symbol] this LLM step's id (for error messages)
+        # @param nodes [Hash{Symbol => Inquirex::Node}, nil]
+        # @return [Hash{Symbol => Hash}] field => { type:, values: } specs
+        def resolve_schema_refs(id, nodes)
+          return {} if @schema_refs.empty?
+
+          overlap = @schema_refs & @schema_fields.keys
+          unless overlap.empty?
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} schema declares #{overlap.map(&:inspect).join(", ")} " \
+              "both as a question reference and an explicit field"
+          end
+
+          @schema_refs.uniq.to_h do |ref|
+            [ref, field_spec_for(id, ref, resolve_question!(id, ref, nodes))]
+          end
+        end
+
+        # Generates a prompt from the referenced questions' own wording.
+        # Runs at build time, after resolution, so the serialized node (and
+        # every adapter) sees a concrete prompt string — `:auto` never
+        # reaches the wire format.
+        #
+        # @param nodes [Hash{Symbol => Inquirex::Node}]
+        # @return [String]
+        def auto_prompt(nodes)
+          lines = @schema_refs.uniq.map do |ref|
+            question = nodes[ref].question
+            question ? "- #{ref}: #{question}" : "- #{ref}"
+          end
+          lines += @schema_fields.map { |name, type| "- #{name} (#{type})" }
+
+          "Extract structured answers from the user's text for the following questions:\n" \
+            "#{lines.join("\n")}\n" \
+            "Only extract what the text supports; leave a field empty or null when unsure."
+        end
+
+        # @return [Inquirex::Node] the ask/confirm step the reference names
+        def resolve_question!(id, ref, nodes)
+          node = nodes&.fetch(ref, nil)
+
+          case node
+          when nil
+            known = (nodes || {}).filter_map { |sid, n| sid if question_node?(n) }
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} schema references unknown question #{ref.inspect}. " \
+              "Known questions: #{known.empty? ? "(none)" : known.map(&:inspect).join(", ")}"
+          when LLM::Node, LlmStepBuilder
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} schema references #{ref.inspect}, which is an LLM step — " \
+              "schema references must name ask/confirm questions"
+          else
+            unless node.collecting?
+              raise Errors::DefinitionError,
+                "LLM step #{id.inspect} schema references #{ref.inspect}, which is a display-only " \
+                "#{node.verb} step — schema references must name ask/confirm questions"
+            end
+            node
+          end
+        end
+
+        def question_node?(node)
+          node.is_a?(Inquirex::Node) && !node.is_a?(LLM::Node) && node.collecting?
+        end
+
+        # @return [Hash] a Schema field spec derived from the question's definition
+        def field_spec_for(id, ref, node)
+          if node.type.nil?
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} schema references #{ref.inspect}, which declares no type"
+          end
+
+          spec = { type: node.type }
+          spec[:values] = node.options if %i[enum multi_enum].include?(node.type) && node.options
+          spec
+        end
+
         def validate!(id)
           raise Errors::DefinitionError, "LLM step #{id.inspect} requires a prompt" if @prompt.nil?
 
+          if @prompt == :auto && @schema_refs.empty?
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} declares `prompt :auto`, which requires schema question " \
+              "references to generate from — declare the schema as question ids (e.g. schema :filing_status)"
+          end
+
           # Schema required for extract (and formerly detour).
-          if %i[extract].include?(@verb) && @schema_fields.empty?
+          if %i[extract].include?(@verb) && @schema_fields.empty? && @schema_refs.empty?
             # if %i[extract detour].include?(@verb) && @schema_fields.empty?
             raise Errors::DefinitionError,
               "LLM step #{id.inspect} (#{@verb}) requires a schema"

data/lib/inquirex/llm/null_adapter.rb

@@ -6,13 +6,15 @@ module Inquirex
     # calling any LLM API. Useful for testing flows that include LLM steps.
     #
     # For extract steps with a schema, returns a hash of default values
-    # matching each field's declared type. Without a schema, returns
-    # a placeholder string.
+    # matching each field's declared type. Fields constrained to a list of
+    # allowed values (enum/multi_enum resolved from questions) return the
+    # first allowed value, so placeholders stay valid answers for the
+    # downstream question. Without a schema, returns a placeholder string.
     #
     # @example
     #   adapter = Inquirex::LLM::NullAdapter.new
     #   result = adapter.call(extract_node, answers)
-    #   # => { industry: "", employee_count: 0, ... }
+    #   # => { industry: "", employee_count: 0, entity_type: "llc", ... }
     class NullAdapter < Adapter
       TYPE_DEFAULTS = {
         string:     "",
@@ -38,12 +40,21 @@ module Inquirex
       def call(node, _answers = {})
         if node.schema
           node.schema.fields.each_with_object({}) do |(name, type), acc|
-            acc[name] = TYPE_DEFAULTS.fetch(type, "")
+            acc[name] = placeholder_for(node.schema, name, type)
           end
         else
           "(placeholder #{node.verb} output for #{node.id})"
         end
       end
+
+      private
+
+      def placeholder_for(schema, name, type)
+        values = schema.values_for(name)
+        return TYPE_DEFAULTS.fetch(type, "") if values.nil? || values.empty?
+
+        type == :multi_enum ? [values.first] : values.first
+      end
     end
   end
 end

data/lib/inquirex/llm/openai_adapter.rb

@@ -88,9 +88,9 @@ module Inquirex
 
       def schema_instruction(node)
         if node.respond_to?(:schema) && node.schema
-          schema_json = node.schema.fields.transform_values(&:to_s)
           "\n\nThe JSON object MUST match this schema exactly (same keys, appropriate types):\n" \
-            "#{JSON.pretty_generate(schema_json)}\n\n" \
+            "#{schema_contract_json(node.schema)}\n" \
+            "#{values_instruction(node.schema)}\n\n" \
             "Every key in the schema must be present in your output. Use null, \"\", 0, or [] " \
             "for values the source text does not provide."
         else
@@ -109,7 +109,7 @@ module Inquirex
 
         if node.respond_to?(:schema) && node.schema
           parts << "\nExtract these fields as a JSON object:"
-          node.schema.fields.each { |field, type| parts << "  #{field} (#{type})" }
+          parts.concat(field_descriptions(node.schema))
         end
 
         if node.respond_to?(:from_all) && node.from_all && all_answers.any?

data/lib/inquirex/llm/schema.rb

@@ -3,21 +3,25 @@
 module Inquirex
   module LLM
     # Immutable definition of expected LLM output structure.
-    # Each field maps a name to an Inquirex data type, forming the contract
-    # between the LLM prompt and the structured data it must return.
+    # Each field maps a name to a spec: an Inquirex data type, plus — for
+    # :enum / :multi_enum fields — the exhaustive list of allowed values.
+    # Together they form the contract between the LLM prompt and the
+    # structured data it must return.
+    #
+    # A field spec is given either as a bare type symbol or as a Hash with
+    # :type and optional :values:
     #
     # @example
     #   schema = Schema.new(
-    #     industry:          :string,
-    #     entity_type:       :enum,
-    #     employee_count:    :integer,
-    #     estimated_revenue: :currency
+    #     industry:       :string,
+    #     employee_count: :integer,
+    #     entity_type:    { type: :enum, values: %w[llc s_corp c_corp] }
     #   )
-    #   schema.fields          # => { industry: :string, ... }
-    #   schema.field_names     # => [:industry, :entity_type, ...]
+    #   schema.fields                    # => { industry: :string, ... }
+    #   schema.values_for(:entity_type)  # => ["llc", "s_corp", "c_corp"]
     #   schema.valid_output?({ industry: "Tech", ... })  # => true
     #
-    # @attr_reader fields [Hash{Symbol => Symbol}] field_name => type mapping
+    # @attr_reader field_specs [Hash{Symbol => Field}] field_name => spec mapping
     class Schema
       VALID_TYPES = %i[
         string text integer decimal currency boolean
@@ -25,25 +29,39 @@ module Inquirex
         array hash
       ].freeze
 
-      attr_reader :fields
+      # A single field's contract: its data type and, for enum-like types,
+      # the allowed values the LLM must choose from.
+      Field = Data.define(:type, :values)
 
-      # @param field_map [Hash{Symbol => Symbol}] field_name => type
+      attr_reader :field_specs
+
+      # @param field_map [Hash{Symbol => Symbol, Hash}] field_name => type,
+      #   or field_name => { type: Symbol, values: Array }
       # @raise [Errors::DefinitionError] if any type is unrecognized
       def initialize(**field_map)
         raise Errors::DefinitionError, "Schema must have at least one field" if field_map.empty?
 
-        validate_types!(field_map)
-        @fields = field_map.transform_keys(&:to_sym)
-                           .transform_values(&:to_sym)
-                           .freeze
+        @field_specs = field_map.to_h { |name, spec| [name.to_sym, build_field(name, spec)] }.freeze
+        @fields = @field_specs.transform_values(&:type).freeze
         freeze
       end
 
+      # @return [Hash{Symbol => Symbol}] field_name => type mapping
+      attr_reader :fields
+
       # @return [Array<Symbol>] ordered list of field names
-      def field_names = @fields.keys
+      def field_names = @field_specs.keys
 
       # @return [Integer] number of fields
-      def size = @fields.size
+      def size = @field_specs.size
+
+      # Allowed values for an enum/multi_enum field, or nil when unconstrained.
+      #
+      # @param name [Symbol, String]
+      # @return [Array<String>, nil]
+      def values_for(name)
+        @field_specs[name.to_sym]&.values
+      end
 
       # Checks whether a Hash output conforms to the schema (all declared fields present).
       #
@@ -53,7 +71,7 @@ module Inquirex
         return false unless output.is_a?(Hash)
 
         symbolized = output.transform_keys(&:to_sym)
-        @fields.keys.all? { |key| symbolized.key?(key) }
+        @field_specs.keys.all? { |key| symbolized.key?(key) }
       end
 
       # Returns the list of fields missing from the given output.
@@ -64,12 +82,23 @@ module Inquirex
         return field_names unless output.is_a?(Hash)
 
         symbolized = output.transform_keys(&:to_sym)
-        @fields.keys.reject { |key| symbolized.key?(key) }
+        @field_specs.keys.reject { |key| symbolized.key?(key) }
       end
 
+      # Wire format. Fields without value constraints serialize as a plain
+      # type string (the pre-0.6 shape); constrained fields serialize as
+      # { "type" => ..., "values" => [...] }.
+      #
       # @return [Hash]
       def to_h
-        @fields.transform_keys(&:to_s).transform_values(&:to_s)
+        @field_specs.each_with_object({}) do |(name, field), acc|
+          acc[name.to_s] =
+            if field.values
+              { "type" => field.type.to_s, "values" => field.values }
+            else
+              field.type.to_s
+            end
+        end
       end
 
       # @return [String] JSON representation
@@ -77,34 +106,52 @@ module Inquirex
         JSON.generate(to_h)
       end
 
-      # @param hash [Hash] string or symbol keys, values are type names
+      # Accepts both wire shapes: plain type strings and rich
+      # { "type" => ..., "values" => [...] } specs.
+      #
+      # @param hash [Hash] string or symbol keys
       # @return [Schema]
       def self.from_h(hash)
         field_map = hash.each_with_object({}) do |(k, v), acc|
-          acc[k.to_sym] = v.to_sym
+          acc[k.to_sym] = v
         end
         new(**field_map)
       end
 
       def ==(other)
-        other.is_a?(Schema) && @fields == other.fields
+        other.is_a?(Schema) && @field_specs == other.field_specs
       end
 
       def inspect
-        "#<Inquirex::LLM::Schema #{@fields.map { |k, v| "#{k}:#{v}" }.join(", ")}>"
+        parts = @field_specs.map do |name, field|
+          field.values ? "#{name}:#{field.type}(#{field.values.join("|")})" : "#{name}:#{field.type}"
+        end
+        "#<Inquirex::LLM::Schema #{parts.join(", ")}>"
       end
 
       private
 
-      def validate_types!(field_map)
-        field_map.each do |name, type|
-          next if VALID_TYPES.include?(type.to_sym)
+      def build_field(name, spec)
+        case spec
+        when Hash
+          type = spec[:type] || spec["type"]
+          values = spec[:values] || spec["values"]
+          raise Errors::DefinitionError, "Field #{name.inspect} spec is missing :type" if type.nil?
 
-          raise Errors::DefinitionError,
-            "Unknown type #{type.inspect} for field #{name.inspect}. " \
-            "Valid types: #{VALID_TYPES.join(", ")}"
+          Field.new(type: validated_type(name, type), values: values&.map(&:to_s)&.freeze)
+        else
+          Field.new(type: validated_type(name, spec), values: nil)
         end
       end
+
+      def validated_type(name, type)
+        sym = type.to_sym
+        return sym if VALID_TYPES.include?(sym)
+
+        raise Errors::DefinitionError,
+          "Unknown type #{type.inspect} for field #{name.inspect}. " \
+          "Valid types: #{VALID_TYPES.join(", ")}"
+      end
     end
   end
 end

data/lib/inquirex/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module LLM
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/inquirex/llm.rb

@@ -42,4 +42,7 @@ end
 
 # Inject LLM verbs into the core FlowBuilder so that Inquirex.define
 # gains extract (and clarify as an alias) when this gem is loaded.
-Inquirex::DSL::FlowBuilder.include(Inquirex::LLM::DSL::FlowBuilderExtension)
+# Prepend (not include): the extension overrides #build to defer LLM node
+# 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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-llm
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
 description: 'Extends the Inquirex DSL with an LLM-powered `extract` verb (alias:
   `clarify`) that runs server-side to turn free-text answers into structured data.
   Pluggable adapter interface keeps the gem LLM-agnostic; a NullAdapter ships for
@@ -34,17 +34,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".relaxed_rubocop.yml"
-- ".rubocop_todo.yml"
-- ".secrets.baseline"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- docs/badges/coverage_badge.svg
 - exe/inquirex-llm
-- justfile
-- lefthook.yml
 - lib/inquirex-llm.rb
 - lib/inquirex/llm.rb
 - lib/inquirex/llm/adapter.rb
@@ -57,7 +50,6 @@ files:
 - lib/inquirex/llm/openai_adapter.rb
 - lib/inquirex/llm/schema.rb
 - lib/inquirex/llm/version.rb
-- sig/inquirex/llm.rbs
 homepage: https://github.com/inquirex/inquirex-llm
 licenses:
 - MIT

data/.relaxed_rubocop.yml

@@ -1,153 +0,0 @@
-# Relaxed.Ruby.Style
-## Version 2.5
-
-Style/Alias:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylealias
-
-Style/AsciiComments:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleasciicomments
-
-Style/BeginBlock:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylebeginblock
-
-Style/BlockDelimiters:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleblockdelimiters
-
-Style/CommentAnnotation:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylecommentannotation
-
-Style/Documentation:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styledocumentation
-
-Layout/DotPosition:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#layoutdotposition
-
-Style/DoubleNegation:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styledoublenegation
-
-Style/EndBlock:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleendblock
-
-Style/FormatString:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleformatstring
-
-Style/IfUnlessModifier:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleifunlessmodifier
-
-Style/Lambda:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylelambda
-
-Style/ModuleFunction:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylemodulefunction
-
-Style/MultilineBlockChain:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylemultilineblockchain
-
-Style/NegatedIf:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylenegatedif
-
-Style/NegatedWhile:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
-
-Style/NumericPredicate:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
-
-Style/ParallelAssignment:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
-
-Style/PercentLiteralDelimiters:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylepercentliteraldelimiters
-
-Style/PerlBackrefs:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styleperlbackrefs
-
-Style/Semicolon:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylesemicolon
-
-Style/SignalException:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylesignalexception
-
-Style/SingleLineBlockParams:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylesinglelineblockparams
-
-Style/SingleLineMethods:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylesinglelinemethods
-
-Layout/SpaceBeforeBlockBraces:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#layoutspacebeforeblockbraces
-
-Layout/SpaceInsideParens:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#layoutspaceinsideparens
-
-Style/SpecialGlobalVars:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylespecialglobalvars
-
-Style/StringLiterals:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylestringliterals
-
-Style/TrailingCommaInArguments:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarguments
-
-Style/TrailingCommaInArrayLiteral:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarrayliteral
-
-Style/TrailingCommaInHashLiteral:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainhashliteral
-
-Style/SymbolArray:
-  Enabled: false
-  StyleGuide: http://relaxed.ruby.style/#stylesymbolarray
-
-Style/WhileUntilModifier:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylewhileuntilmodifier
-
-Style/WordArray:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#stylewordarray
-
-Lint/AmbiguousRegexpLiteral:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
-
-Lint/AssignmentInCondition:
-  Enabled: false
-  StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
-
-Layout/LineLength:
-  Enabled: false
-
-Metrics:
-  Enabled: false
-

data/.rubocop_todo.yml

@@ -1,28 +0,0 @@
-# This configuration was generated by
-# `rubocop --auto-gen-config`
-# on 2026-04-14 23:51:42 UTC using RuboCop version 1.86.1.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 1
-# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
-# SupportedStyles: snake_case, normalcase, non_integer
-# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
-Naming/VariableNumber:
-  Exclude:
-    - 'lib/inquirex/llm/openai_adapter.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowSubject.
-RSpec/MultipleMemoizedHelpers:
-  Max: 6
-
-# Offense count: 1
-# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
-# SupportedInflectors: default, active_support
-RSpec/SpecFilePathFormat:
-  Exclude:
-    - '**/spec/routing/**/*'
-    - 'spec/inquirex/llm/openai_adapter_spec.rb'

data/.secrets.baseline

@@ -1,127 +0,0 @@
-{
-  "version": "1.5.0",
-  "plugins_used": [
-    {
-      "name": "ArtifactoryDetector"
-    },
-    {
-      "name": "AWSKeyDetector"
-    },
-    {
-      "name": "AzureStorageKeyDetector"
-    },
-    {
-      "name": "Base64HighEntropyString",
-      "limit": 4.5
-    },
-    {
-      "name": "BasicAuthDetector"
-    },
-    {
-      "name": "CloudantDetector"
-    },
-    {
-      "name": "DiscordBotTokenDetector"
-    },
-    {
-      "name": "GitHubTokenDetector"
-    },
-    {
-      "name": "GitLabTokenDetector"
-    },
-    {
-      "name": "HexHighEntropyString",
-      "limit": 3.0
-    },
-    {
-      "name": "IbmCloudIamDetector"
-    },
-    {
-      "name": "IbmCosHmacDetector"
-    },
-    {
-      "name": "IPPublicDetector"
-    },
-    {
-      "name": "JwtTokenDetector"
-    },
-    {
-      "name": "KeywordDetector",
-      "keyword_exclude": ""
-    },
-    {
-      "name": "MailchimpDetector"
-    },
-    {
-      "name": "NpmDetector"
-    },
-    {
-      "name": "OpenAIDetector"
-    },
-    {
-      "name": "PrivateKeyDetector"
-    },
-    {
-      "name": "PypiTokenDetector"
-    },
-    {
-      "name": "SendGridDetector"
-    },
-    {
-      "name": "SlackDetector"
-    },
-    {
-      "name": "SoftlayerDetector"
-    },
-    {
-      "name": "SquareOAuthDetector"
-    },
-    {
-      "name": "StripeDetector"
-    },
-    {
-      "name": "TelegramBotTokenDetector"
-    },
-    {
-      "name": "TwilioKeyDetector"
-    }
-  ],
-  "filters_used": [
-    {
-      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
-    },
-    {
-      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
-      "min_level": 2
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_lock_file"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_sequential_string"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_swagger_file"
-    },
-    {
-      "path": "detect_secrets.filters.heuristic.is_templated_secret"
-    }
-  ],
-  "results": {},
-  "generated_at": "2026-04-13T21:29:03Z"
-}

data/Rakefile

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "timeout"
-require "yard"
-
-def shell(*args)
-  puts "running: #{args.join(" ")}"
-  system(args.join(" "))
-end
-
-task :clean do
-  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
-end
-
-task gem: [:build] do
-  shell("gem install pkg/*")
-end
-
-task permissions: [:clean] do
-  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
-  shell("find . -type d -exec chmod o+x,g+x {} \\;")
-end
-
-task build: :permissions
-
-YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
-  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
-  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
-end
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/docs/badges/coverage_badge.svg

@@ -1,21 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
-  <linearGradient id="b" x2="0" y2="100%">
-    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
-    <stop offset="1" stop-opacity=".1"/>
-  </linearGradient>
-  <mask id="a">
-    <rect width="99" height="20" rx="3" fill="#fff"/>
-  </mask>
-  <g mask="url(#a)">
-    <path fill="#555" d="M0 0h63v20H0z"/>
-    <path fill="#4c1" d="M63 0h36v20H63z"/>
-    <path fill="url(#b)" d="M0 0h99v20H0z"/>
-  </g>
-  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
-    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
-    <text x="31.5" y="14">coverage</text>
-    <text x="80" y="15" fill="#010101" fill-opacity=".3">98%</text>
-    <text x="80" y="14">98%</text>
-  </g>
-</svg>

data/justfile

@@ -1,69 +0,0 @@
-# Tell 'just' to run bash, source our setup script, then execute the recipe
-set shell := ["bash", "-c"]
-
-version := `grep VERSION lib/inquirex/llm/version.rb | awk '{print $3}' | tr -d '"' | tr -d '\n'`
-rbenv   := 'eval "$(rbenv init bash)"; bundle exec '
-repo    := 'git@github.com:inquirex/inquirex.git'
-
-[no-exit-message]
-recipes:
-    just --choose
-
-# Sync all dependencies
-install:
-    bin/setup
-
-build: install
-
-# Lint and reformat files
-lint:
-    {{ rbenv }} rubocop
-
-# Lint and reformat files (-a) — pass -A as an argument
-format *args:
-    {{ rbenv }} rubocop -a {{ args }}
-
-# Run all the tests
-test *args: 
-    export ENVIRONMENT=test; {{ rbenv }} rspec {{args}}
-
-# Run tests with coverage
-test-coverage *args:
-    export ENVIRONMENT=test; export COVERAGE=true; {{ rbenv }} rspec {{ args }}
-
-check-all: install lint test-coverage 
-
-clean:
-    #!/usr/bin/env bash
-    @find . -name .DS_Store -delete -print || true
-    @rm -rf tmp/*
-
-# Run all lefthook pre-commit hooks
-lefthook:
-    {{ rbenv }} lefthook run pre-commit --all-files
-
-# Print current gem version
-version:
-    @echo "{{ version }}"
-
-# Clobber
-clobber: 
-    {{ rbenv }} rake clobber
-
-# Generate documentation
-doc: 
-    #!/usr/bin/env bash
-    {{ rbenv }} rake doc
-
-# Create
-publish: build
-    {{ rbenv }} rake release[remote]
-
-
-# Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
-release:
-    git fetch --tags
-    git tag -f "v{{ version }}"
-    git push -f --tags
-    gh release delete -y "v{{ version }}" --repo {{ repo }} 2>/dev/null || true
-    gh release create "v{{ version }}" --generate-notes --repo {{ repo }}

data/lefthook.yml

@@ -1,35 +0,0 @@
-output:
-  - summary
-  - failure
-
-pre-commit:
-  parallel: true
-  jobs:
-    - name: lint
-      run: bundle exec rubocop -c .rubocop.yml {staged_files}
-      glob: "*.{rb,Gemfile}"
-      stage_fixed: true
-
-    - name: check for conflict markers and whitespace issues
-      run: git --no-pager diff --check
-
-    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
-    - name: run tests
-      run: just test
-
-    - name: fix rubocop formatting issues
-      run: bundle exec rubocop -a {staged_files}
-      glob: "*.{rb,Gemfile,gemspec}"
-      stage_fixed: true
-
-    - name: spell check
-      run: codespell {staged_files}
-      glob: "*.{rb,md,gemspec}"
-
-    - name: format markdown
-      run: mdformat {staged_files}
-      glob: "*.md"
-      stage_fixed: true
-
-    - name: scan for secrets
-      run: detect-secrets-hook --baseline .secrets.baseline

data/sig/inquirex/llm.rbs

@@ -1,6 +0,0 @@
-module Inquirex
-  module Llm
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-  end
-end