inquirex-llm 0.1.0

data/lib/inquirex/llm/adapter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    # Abstract interface for LLM adapters. Adapters bridge the gap between
+    # LLM::Node definitions and actual LLM API calls.
+    #
+    # Implementations must:
+    #   1. Accept an LLM::Node and current answers
+    #   2. Construct the appropriate prompt (using node.prompt, node.from_steps, etc.)
+    #   3. Call the LLM API
+    #   4. Parse and validate the response against node.schema (if present)
+    #   5. Return a Hash or String result
+    #
+    # The adapter is invoked server-side when the engine reaches an LLM step.
+    # It is never called on the frontend.
+    #
+    # @example Implementing a custom adapter
+    #   class MyLlmAdapter < Inquirex::LLM::Adapter
+    #     def call(node, answers)
+    #       prompt_text = build_prompt(node, answers)
+    #       response = my_llm_client.complete(prompt_text, model: node.model)
+    #       parse_response(response, node.schema)
+    #     end
+    #   end
+    class Adapter
+      # Processes an LLM step and returns the result.
+      #
+      # @param node [LLM::Node] the LLM step to process
+      # @param answers [Hash] current collected answers
+      # @return [Hash, String] structured output (for clarify/detour) or text (for describe/summarize)
+      # @raise [Errors::AdapterError] if the LLM call fails
+      # @raise [Errors::SchemaViolationError] if output doesn't match schema
+      def call(node, answers)
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      # Gathers the source answer data that feeds the LLM prompt.
+      #
+      # @param node [LLM::Node]
+      # @param answers [Hash]
+      # @return [Hash] relevant subset of answers
+      def source_answers(node, answers)
+        if node.from_all
+          answers.dup
+        else
+          node.from_steps.each_with_object({}) do |step_id, acc|
+            acc[step_id] = answers[step_id] if answers.key?(step_id)
+          end
+        end
+      end
+
+      # Validates adapter output against the node's schema.
+      #
+      # @param node [LLM::Node]
+      # @param output [Hash, String]
+      # @raise [Errors::SchemaViolationError] if validation fails
+      def validate_output!(node, output)
+        return unless node.schema
+
+        missing = node.schema.missing_fields(output)
+        return if missing.empty?
+
+        raise Errors::SchemaViolationError,
+          "LLM output for #{node.id.inspect} missing fields: #{missing.join(", ")}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    module DSL
+      # Mixin that adds LLM verb methods to Inquirex::DSL::FlowBuilder.
+      # Included automatically when `require "inquirex-llm"` is called,
+      # so that `Inquirex.define` gains clarify/describe/summarize/detour
+      # without needing a separate entry point.
+      #
+      # All core verbs (ask, say, header, btw, warning, confirm) remain
+      # unchanged — LLM verbs are purely additive.
+      module FlowBuilderExtension
+        # Defines an LLM extraction step: takes free-text input and produces
+        # structured data matching the declared schema.
+        #
+        # @param id [Symbol] step id
+        def clarify(id, &)
+          add_llm_step(id, :clarify, &)
+        end
+
+        # Defines an LLM description step: takes structured data and produces
+        # natural-language text.
+        #
+        # @param id [Symbol] step id
+        def describe(id, &)
+          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
+
+        # Defines an LLM detour step: based on an answer, dynamically generates
+        # follow-up questions. The server adapter handles presenting the generated
+        # questions and collecting responses.
+        #
+        # @param id [Symbol] step id
+        def detour(id, &)
+          add_llm_step(id, :detour, &)
+        end
+
+        private
+
+        # Uses the standard Ruby builder pattern (same as core FlowBuilder#add_step).
+        def add_llm_step(id, verb, &block)
+          builder = LlmStepBuilder.new(verb)
+          builder.instance_eval(&block) if block
+          @nodes[id.to_sym] = builder.build(id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    module DSL
+      # Builds an LLM::Node from a step DSL block. Handles the LLM-specific
+      # methods (from, prompt, schema, model, temperature, max_tokens, fallback)
+      # while inheriting transition and skip_if from the core StepBuilder.
+      #
+      # @example
+      #   clarify :business_extracted do
+      #     from :business_description
+      #     prompt "Extract structured business info."
+      #     schema industry: :string, employee_count: :integer
+      #     model :claude_sonnet
+      #     temperature 0.2
+      #     transition to: :next_step
+      #   end
+      class LlmStepBuilder
+        include Inquirex::DSL::RuleHelpers
+
+        def initialize(verb)
+          @verb = verb.to_sym
+          @prompt = nil
+          @schema_fields = {}
+          @from_steps = []
+          @from_all = false
+          @model = nil
+          @temperature = nil
+          @max_tokens = nil
+          @fallback = nil
+          @transitions = []
+          @skip_if = nil
+          @question = nil
+          @text = nil
+        end
+
+        # Sets the LLM prompt template. Use {{field_name}} for interpolation
+        # placeholders that the adapter resolves at runtime.
+        #
+        # @param text [String]
+        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.
+        #
+        # @param fields [Hash{Symbol => Symbol}]
+        def schema(**fields)
+          @schema_fields.merge!(fields)
+        end
+
+        # Adds source step id(s) whose answers feed the LLM prompt.
+        #
+        # @param step_ids [Symbol, Array<Symbol>] one or more step ids
+        def from(*step_ids)
+          @from_steps.concat(step_ids.flatten)
+        end
+
+        # Passes all collected answers to the LLM prompt.
+        #
+        # @param value [Boolean]
+        def from_all(value = true)
+          @from_all = !!value
+        end
+
+        # Optional model hint for the adapter.
+        #
+        # @param name [Symbol] e.g. :claude_sonnet, :claude_haiku
+        def model(name)
+          @model = name.to_sym
+        end
+
+        # Optional sampling temperature.
+        #
+        # @param value [Float]
+        def temperature(value)
+          @temperature = value.to_f
+        end
+
+        # Optional maximum output tokens.
+        #
+        # @param value [Integer]
+        def max_tokens(value)
+          @max_tokens = value.to_i
+        end
+
+        # Server-side fallback block, invoked when the LLM call fails.
+        # Stripped from JSON serialization.
+        #
+        # @yield [Hash] answers collected so far
+        # @return [Object] fallback value to store as the answer
+        def fallback(&block)
+          @fallback = block
+        end
+
+        # Adds a conditional transition. Inherited concept from core DSL.
+        # All LLM transitions are implicitly requires_server: true.
+        #
+        # @param to [Symbol] target step id
+        # @param if_rule [Rules::Base, nil]
+        # @param requires_server [Boolean]
+        def transition(to:, if_rule: nil, requires_server: true)
+          @transitions << Inquirex::Transition.new(target: to, rule: if_rule, requires_server:)
+        end
+
+        # Sets a rule that skips this step entirely when true.
+        #
+        # @param rule [Rules::Base]
+        def skip_if(rule)
+          @skip_if = rule
+        end
+
+        # Optional display text (used by describe/summarize for user-visible labels).
+        #
+        # @param content [String]
+        def question(content)
+          @question = content
+        end
+
+        # Optional display text for context.
+        #
+        # @param content [String]
+        def text(content)
+          @text = content
+        end
+
+        # Builds the LLM::Node.
+        #
+        # @param id [Symbol]
+        # @return [LLM::Node]
+        # @raise [Errors::DefinitionError] if prompt is missing
+        def build(id)
+          validate!(id)
+
+          schema_obj = @schema_fields.empty? ? nil : Schema.new(**@schema_fields)
+
+          LLM::Node.new(
+            id:,
+            verb:        @verb,
+            prompt:      @prompt,
+            schema:      schema_obj,
+            from_steps:  @from_steps,
+            from_all:    @from_all,
+            model:       @model,
+            temperature: @temperature,
+            max_tokens:  @max_tokens,
+            fallback:    @fallback,
+            question:    @question,
+            text:        @text,
+            transitions: @transitions,
+            skip_if:     @skip_if
+          )
+        end
+
+        private
+
+        def validate!(id)
+          raise Errors::DefinitionError, "LLM step #{id.inspect} requires a prompt" if @prompt.nil?
+
+          if %i[clarify detour].include?(@verb) && @schema_fields.empty?
+            raise Errors::DefinitionError,
+              "LLM step #{id.inspect} (#{@verb}) requires a schema"
+          end
+
+          return unless @from_steps.empty? && !@from_all && @verb != :summarize
+
+          # clarify/describe/detour should reference source steps or from_all
+          return unless %i[clarify describe detour].include?(@verb)
+
+          raise Errors::DefinitionError,
+            "LLM step #{id.inspect} (#{@verb}) requires `from` or `from_all`"
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/llm/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    module Errors
+      # Base exception for all LLM-related errors.
+      class Error < Inquirex::Errors::Error; end
+
+      # Raised when an LLM step definition is invalid (e.g. missing prompt, bad schema).
+      class DefinitionError < Error; end
+
+      # Raised when the LLM adapter returns output that doesn't match the declared schema.
+      class SchemaViolationError < Error; end
+
+      # Raised when the LLM adapter call fails after exhausting retries.
+      class AdapterError < Error; end
+    end
+  end
+end

data/lib/inquirex/llm/node.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    # Enriched node for LLM-powered steps. Extends Inquirex::Node with attributes
+    # needed by the server-side LLM adapter: prompt template, output schema, source
+    # step references, and model configuration.
+    #
+    # LLM verbs:
+    #   :clarify   — extract structured data from a free-text answer
+    #   :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
+    #
+    # All LLM nodes are collecting (they produce answers) and require server
+    # round-trips. The frontend shows a "thinking" state while the server processes.
+    #
+    # @attr_reader prompt [String] LLM prompt template
+    # @attr_reader schema [Schema, nil] expected output structure (required for clarify/detour)
+    # @attr_reader from_steps [Array<Symbol>] source step ids whose answers feed the LLM
+    # @attr_reader from_all [Boolean] whether to pass all collected answers to the LLM
+    # @attr_reader model [Symbol, nil] optional model hint (e.g. :claude_sonnet)
+    # @attr_reader temperature [Float, nil] optional sampling temperature
+    # @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[clarify describe summarize detour].freeze
+
+      attr_reader :prompt,
+        :schema,
+        :from_steps,
+        :from_all,
+        :model,
+        :temperature,
+        :max_tokens,
+        :fallback
+
+      def initialize(prompt:, schema: nil, from_steps: [], from_all: false,
+        model: nil, temperature: nil, max_tokens: nil, fallback: nil, **)
+        @prompt = prompt
+        @schema = schema
+        @from_steps = Array(from_steps).map(&:to_sym).freeze
+        @from_all = !!from_all
+        @model = model&.to_sym
+        @temperature = temperature&.to_f
+        @max_tokens = max_tokens&.to_i
+        @fallback = fallback
+        super(**)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # LLM verbs always collect output (the LLM provides the "answer").
+      def collecting? = true
+
+      # LLM verbs are never display-only.
+      def display? = false
+
+      # Whether this is an LLM-powered step requiring server processing.
+      def llm_verb? = true
+
+      # 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.
+      #
+      # @return [Hash]
+      def to_h
+        hash = { "verb" => @verb.to_s }
+        hash["question"] = @question if @question
+        hash["text"] = @text if @text
+        hash["transitions"] = @transitions.map(&:to_h) unless @transitions.empty?
+        hash["skip_if"] = @skip_if.to_h if @skip_if
+        hash["requires_server"] = true
+
+        llm_hash = { "prompt" => @prompt }
+        llm_hash["schema"] = @schema.to_h if @schema
+        llm_hash["from_steps"] = @from_steps.map(&:to_s) unless @from_steps.empty?
+        llm_hash["from_all"] = true if @from_all
+        llm_hash["model"] = @model.to_s if @model
+        llm_hash["temperature"] = @temperature if @temperature
+        llm_hash["max_tokens"] = @max_tokens if @max_tokens
+        hash["llm"] = llm_hash
+
+        hash
+      end
+
+      # Deserializes from a plain Hash (string or symbol keys).
+      #
+      # @param id [Symbol, String]
+      # @param hash [Hash]
+      # @return [LLM::Node]
+      def self.from_h(id, hash)
+        verb             = hash["verb"]        || hash[:verb]
+        question         = hash["question"]    || hash[:question]
+        text             = hash["text"]        || hash[:text]
+        transitions_data = hash["transitions"] || hash[:transitions] || []
+        skip_if_data     = hash["skip_if"]     || hash[:skip_if]
+        llm_data         = hash["llm"]         || hash[:llm] || {}
+
+        transitions = transitions_data.map { |t| Inquirex::Transition.from_h(t) }
+        skip_if = skip_if_data ? Inquirex::Rules::Base.from_h(skip_if_data) : nil
+
+        prompt     = llm_data["prompt"]     || llm_data[:prompt]
+        schema_raw = llm_data["schema"]     || llm_data[:schema]
+        from_raw   = llm_data["from_steps"] || llm_data[:from_steps] || []
+        from_all   = llm_data["from_all"]   || llm_data[:from_all] || false
+        model      = llm_data["model"]      || llm_data[:model]
+        temp       = llm_data["temperature"] || llm_data[:temperature]
+        max_tok    = llm_data["max_tokens"]  || llm_data[:max_tokens]
+
+        schema = schema_raw ? Schema.from_h(schema_raw) : nil
+        from_steps = from_raw.map(&:to_sym)
+
+        new(
+          id:,
+          verb:,
+          question:,
+          text:,
+          transitions:,
+          skip_if:,
+          prompt:,
+          schema:,
+          from_steps:,
+          from_all:,
+          model:,
+          temperature: temp,
+          max_tokens:  max_tok
+        )
+      end
+
+      # Whether this verb is a recognized LLM verb.
+      def self.llm_verb?(verb)
+        LLM_VERBS.include?(verb.to_sym)
+      end
+    end
+  end
+end

data/lib/inquirex/llm/null_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    # Test adapter that returns schema-conformant placeholder values without
+    # calling any LLM API. Useful for testing flows that include LLM steps.
+    #
+    # For clarify/detour steps with a schema, returns a hash of default values
+    # matching each field's declared type. For describe/summarize steps, returns
+    # a placeholder string.
+    #
+    # @example
+    #   adapter = Inquirex::LLM::NullAdapter.new
+    #   result = adapter.call(clarify_node, answers)
+    #   # => { industry: "", employee_count: 0, ... }
+    class NullAdapter < Adapter
+      TYPE_DEFAULTS = {
+        string:     "",
+        text:       "",
+        integer:    0,
+        decimal:    0.0,
+        currency:   0.0,
+        boolean:    false,
+        enum:       "",
+        multi_enum: [],
+        date:       "",
+        email:      "",
+        phone:      "",
+        array:      [],
+        hash:       {}
+      }.freeze
+
+      # Returns placeholder output matching the node's schema or verb.
+      #
+      # @param node [LLM::Node]
+      # @param _answers [Hash] ignored
+      # @return [Hash, String]
+      def call(node, _answers = {})
+        if node.schema
+          node.schema.fields.each_with_object({}) do |(name, type), acc|
+            acc[name] = TYPE_DEFAULTS.fetch(type, "")
+          end
+        else
+          "(placeholder #{node.verb} output for #{node.id})"
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/llm/schema.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # @example
+    #   schema = Schema.new(
+    #     industry:          :string,
+    #     entity_type:       :enum,
+    #     employee_count:    :integer,
+    #     estimated_revenue: :currency
+    #   )
+    #   schema.fields          # => { industry: :string, ... }
+    #   schema.field_names     # => [:industry, :entity_type, ...]
+    #   schema.valid_output?({ industry: "Tech", ... })  # => true
+    #
+    # @attr_reader fields [Hash{Symbol => Symbol}] field_name => type mapping
+    class Schema
+      VALID_TYPES = %i[
+        string text integer decimal currency boolean
+        enum multi_enum date email phone
+        array hash
+      ].freeze
+
+      attr_reader :fields
+
+      # @param field_map [Hash{Symbol => Symbol}] field_name => type
+      # @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
+        freeze
+      end
+
+      # @return [Array<Symbol>] ordered list of field names
+      def field_names = @fields.keys
+
+      # @return [Integer] number of fields
+      def size = @fields.size
+
+      # Checks whether a Hash output conforms to the schema (all declared fields present).
+      #
+      # @param output [Hash] LLM output to validate
+      # @return [Boolean]
+      def valid_output?(output)
+        return false unless output.is_a?(Hash)
+
+        symbolized = output.transform_keys(&:to_sym)
+        @fields.keys.all? { |key| symbolized.key?(key) }
+      end
+
+      # Returns the list of fields missing from the given output.
+      #
+      # @param output [Hash]
+      # @return [Array<Symbol>]
+      def missing_fields(output)
+        return field_names unless output.is_a?(Hash)
+
+        symbolized = output.transform_keys(&:to_sym)
+        @fields.keys.reject { |key| symbolized.key?(key) }
+      end
+
+      # @return [Hash]
+      def to_h
+        @fields.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      # @return [String] JSON representation
+      def to_json(*)
+        JSON.generate(to_h)
+      end
+
+      # @param hash [Hash] string or symbol keys, values are type names
+      # @return [Schema]
+      def self.from_h(hash)
+        field_map = hash.each_with_object({}) do |(k, v), acc|
+          acc[k.to_sym] = v.to_sym
+        end
+        new(**field_map)
+      end
+
+      def ==(other)
+        other.is_a?(Schema) && @fields == other.fields
+      end
+
+      def inspect
+        "#<Inquirex::LLM::Schema #{@fields.map { |k, v| "#{k}:#{v}" }.join(", ")}>"
+      end
+
+      private
+
+      def validate_types!(field_map)
+        field_map.each do |name, type|
+          next if VALID_TYPES.include?(type.to_sym)
+
+          raise Errors::DefinitionError,
+            "Unknown type #{type.inspect} for field #{name.inspect}. " \
+            "Valid types: #{VALID_TYPES.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/llm/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module LLM
+    VERSION = "0.1.0"
+  end
+end

data/lib/inquirex/llm.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "inquirex"
+require "json"
+
+require_relative "llm/version"
+require_relative "llm/errors"
+require_relative "llm/schema"
+require_relative "llm/node"
+require_relative "llm/adapter"
+require_relative "llm/null_adapter"
+require_relative "llm/dsl/llm_step_builder"
+require_relative "llm/dsl/flow_builder"
+
+module Inquirex
+  # LLM integration layer for Inquirex flows.
+  #
+  # Extends the core DSL with four LLM-powered verbs that run server-side:
+  #   - clarify   — extract structured data from free-text answers
+  #   - 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`
+  # in the JSON wire format so the JS widget knows to round-trip to the server.
+  #
+  # Usage:
+  #   require "inquirex"
+  #   require "inquirex-llm"
+  #
+  #   Inquirex.define id: "intake" do
+  #     start :description
+  #     ask(:description) { type :text; question "Describe your business."; transition to: :extracted }
+  #     clarify(:extracted) { from :description; prompt "Extract info."; schema name: :string; transition to: :done }
+  #     say(:done) { text "Done!" }
+  #   end
+  module LLM
+  end
+end
+
+# Inject LLM verbs into the core FlowBuilder so that Inquirex.define
+# gains clarify/describe/summarize/detour when this gem is loaded.
+Inquirex::DSL::FlowBuilder.include(Inquirex::LLM::DSL::FlowBuilderExtension)

data/lib/inquirex-llm.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "inquirex/llm"

data/sig/inquirex/llm.rbs

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