inquirex-llm 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 737239fae63381a1b7ab52afd9a811e6d57f4b781379c8dbaa694c7458e940a2
-  data.tar.gz: 531baf672a53604111e9799bdb2a1af4bfac01933a304589da6c68655db57dfb
+  metadata.gz: db7e0d183259c896f2b1b5d9bd6ce1808f3a0c89de415a7129d2da2133a1ea49
+  data.tar.gz: dc3a1659f93182d83972dfccaaacbec820509823c293a97de4ac6df596409701
 SHA512:
-  metadata.gz: 5a372a04fd14caddf249fd5b04d63f87508dc468ea50de016f57ac968814f4b8641fe96e6b05f05bc433a2c77978ffd120b4529a3ae5590867da46eb4e5f00e4
-  data.tar.gz: f8b604991408d6b61a063a9f337e32fe8de96c0de5b6eda7bf08dfe496f19756833abae6c3437cf6078c9efe5ff5230c05f14f3b0ea2e205b68c9efc8d7bb416
+  metadata.gz: 6b8e8a8c3069ae95d904e3635d3b4947997e812d678dbf562040ae0647563692edef7364977e20ac2eb972d18d3aaeed88f606a1b05fc2d842ba201ff487b748
+  data.tar.gz: a3d8a7a89d4f22b7c3420ae1b22114895bee402314b6e4d303dfd3702f8afae1aeb87eac9a35e53090279a188b2d838c56759a8d2cecfc31179006f64d0d8fe7

data/README.md

@@ -1,27 +1,31 @@
-[![Ruby](https://github.com/inquirex/inquirex-llm/actions/workflows/main.yml/badge.svg)](https://github.com/inquirex/inquirex-llm/actions/workflows/main.yml)  ![Coverage](docs/badges/coverage_badge.svg)
+[![Gem Version](https://badge.fury.io/rb/inquirex-llm.svg)](https://badge.fury.io/rb/inquirex-llm) [![Ruby](https://github.com/inquirex/inquirex-llm/actions/workflows/main.yml/badge.svg)](https://github.com/inquirex/inquirex-llm/actions/workflows/main.yml) ![Coverage](docs/badges/coverage_badge.svg)
 
 # inquirex-llm
 
 LLM integration verbs for the [Inquirex](https://github.com/inquirex/inquirex) questionnaire engine.
 
-Extends the core DSL with four server-side verbs -- `clarify`, `describe`, `summarize`, and `detour` -- that bridge free-text answers and structured data via LLM processing. Ships with a pluggable adapter interface and a `NullAdapter` for testing.
+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.)
 
-## Status
+`inquirex` is a pure Ruby, declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys.
 
-- Version: `0.1.0`
-- Ruby: `>= 4.0.0`
-- Test suite: `111 examples, 0 failures`
-- Depends on: `inquirex` (core gem)
-
-## Installation
-
-```ruby
-gem "inquirex-llm"
-```
+> [!IMPORTANT]
+>
+> Note that `inquirex-llm` is part of an entire ecosystem that contains:
+>
+> - [`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))
+>
+> 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).
+>
+> 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.
 
 ## Usage
 
-`require "inquirex-llm"` injects the LLM verbs into the core `Inquirex.define` DSL. No separate entry point needed.
+`require "inquirex-llm"` injects the LLM verbs into the core `Inquirex.define` DSL.
+
+No separate entry point needed.
 
 ```ruby
 require "inquirex"
@@ -36,7 +40,7 @@ definition = Inquirex.define id: "tax-intake-2026", version: "1.0.0" do
     transition to: :extracted
   end
 
-  clarify :extracted do
+  extract :extracted do
     from :description
     prompt "Extract structured business information from the description."
     schema industry:          :string,
@@ -45,15 +49,9 @@ definition = Inquirex.define id: "tax-intake-2026", version: "1.0.0" do
            estimated_revenue: :currency
     model :claude_sonnet
     temperature 0.2
-    transition to: :summary
-  end
-
-  summarize :summary do
-    from_all
-    prompt "Summarize this client's tax situation and flag complexity concerns."
     transition to: :done
   end
-
+  
   say :done do
     text "Thank you! We'll be in touch."
   end
@@ -62,14 +60,14 @@ end
 
 All core verbs (`ask`, `say`, `header`, `btw`, `warning`, `confirm`) and widget hints work alongside LLM verbs in the same `Inquirex.define` block.
 
-## LLM Verbs
+## Currently Supported LLM Verbs
 
-### `clarify`
+### `extract` (alias: `clarify`)
 
-Extract structured data from a free-text answer. Requires `from`, `prompt`, and `schema`.
+Extract structured data from a free-text answer. Requires `from` (or `from_all`), `prompt`, and `schema`. The stored/serialized verb is always `"extract"`; `clarify` is a DSL-only alias.
 
 ```ruby
-clarify :business_extracted do
+extract :business_extracted do
   from :business_description
   prompt "Extract structured business information."
   schema industry: :string, employee_count: :integer, revenue: :currency
@@ -80,57 +78,20 @@ clarify :business_extracted do
 end
 ```
 
-### `describe`
-
-Generate natural-language text from structured data. Requires `from` and `prompt`. No schema needed.
-
-```ruby
-describe :business_narrative do
-  from :business_extracted
-  prompt "Write a brief narrative of this business for the intake report."
-  transition to: :next_step
-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`
-
-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`.
-
-```ruby
-detour :followup do
-  from :description
-  prompt "Generate 2-3 follow-up questions to clarify the tax situation."
-  schema questions: :array, answers: :hash
-  transition to: :next_step
-end
-```
-
 ## DSL Methods (inside LLM verb blocks)
 
-| Method | Purpose | Required |
-|--------|---------|----------|
-| `prompt "..."` | LLM prompt template | Always |
-| `schema key: :type, ...` | Expected output structure | `clarify`, `detour` |
-| `from :step_id` | Source step(s) whose answers feed the LLM | `clarify`, `describe`, `detour` |
-| `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 "..."`                 | 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                            |
 
 ## Engine Integration
 
@@ -161,16 +122,14 @@ result = adapter.call(engine.current_step)
 
 ## Built-in Adapters
 
-| Class | Provider | API | Auth | Key env var |
-|------------------------------------|-----------|---------------------------------------|-----------------------------|-----------------------|
-| `Inquirex::LLM::NullAdapter` | — | none (placeholders) | none | — |
-| `Inquirex::LLM::AnthropicAdapter` | Anthropic | `/v1/messages` | `x-api-key` header | `ANTHROPIC_API_KEY` |
-| `Inquirex::LLM::OpenAIAdapter` | OpenAI | `/v1/chat/completions` (JSON mode) | `Authorization: Bearer …` | `OPENAI_API_KEY` |
+| Class                                   | Provider  | API                                | Auth                      | Key env var         |
+| --------------------------------------- | --------- | ---------------------------------- | ------------------------- | ------------------- |
+| `Inquirex::LLM::NullAdapter`            | —         | none (placeholders)                | none                      | —                   |
+| `Inquirex::LLM::AnthropicAdapter`       | Anthropic | `/v1/messages`                     | `x-api-key` header        | `ANTHROPIC_API_KEY` |
+| `Inquirex::LLM::OpenAIAdapter`          | OpenAI    | `/v1/chat/completions` (JSON mode) | `Authorization: Bearer …` | `OPENAI_API_KEY`    |
+| `Inquirex::LLM::LittleLLMAdapter` (TBD) | Any       | OpenAI Compatible API              | OpenAI Compatible Auth    | Provider Specific   |
 
-Both real adapters use `net/http` (stdlib, no extra dependency), inject the
-declared `schema` into the system prompt as a strict JSON contract, and raise
-`Inquirex::LLM::Errors::AdapterError` on HTTP / parse failures and
-`SchemaViolationError` when the model's output is missing declared fields.
+The Anthropic and OpenAI adapters use `net/http` (stdlib, no extra dependency), inject the declared `schema` into the system prompt as a strict JSON contract, and raise `Inquirex::LLM::Errors::AdapterError` on HTTP / parse failures and `SchemaViolationError` when the model's output is missing declared fields.
 
 ### AnthropicAdapter
 
@@ -181,8 +140,7 @@ adapter = Inquirex::LLM::AnthropicAdapter.new(
 )
 ```
 
-Recognized `model :symbol` values in the DSL: `:claude_sonnet`,
-`:claude_haiku`, `:claude_opus` (mapped to the current concrete model ids).
+Recognized `model :symbol` values in the DSL: `:claude_sonnet`, `:claude_haiku`, `:claude_opus` (mapped to the current concrete model ids).
 
 ### OpenAIAdapter
 
@@ -193,18 +151,11 @@ adapter = Inquirex::LLM::OpenAIAdapter.new(
 )
 ```
 
-Uses Chat Completions with `response_format: { type: "json_object" }` so the
-model is constrained to return valid JSON. Recognized DSL symbols: `:gpt_4o`,
-`:gpt_4o_mini`, `:gpt_4_1`, `:gpt_4_1_mini`. For cross-provider portability,
-the adapter also accepts the Claude symbols (`:claude_sonnet` → `gpt-4o` etc.)
-so a flow file that says `model :claude_sonnet` runs unchanged against either
-provider.
+Uses Chat Completions with `response_format: { type: "json_object" }` so the model is constrained to return valid JSON. Recognized DSL symbols: `:gpt_4o`, `:gpt_4o_mini`, `:gpt_4_1`, `:gpt_4_1_mini`. For cross-provider portability, the adapter also accepts the Claude symbols (`:claude_sonnet` → `gpt-4o` etc.) so a flow file that says `model :claude_sonnet` runs unchanged against either provider.
 
 ## LLM-assisted Pre-fill Pattern
 
-A common use case: ask *one* open-ended question, let the LLM extract answers
-for *many* downstream questions, and only prompt the user for what the LLM
-couldn't determine. This is what the core engine's `Engine#prefill!` is for:
+A common use case: ask *one* open-ended question, let the LLM extract answers for *many* downstream questions, and only prompt the user for what the LLM couldn't determine. This is what the core engine's `Engine#prefill!` is for:
 
 ```ruby
 definition = Inquirex.define id: "tax-intake" do
@@ -216,7 +167,7 @@ definition = Inquirex.define id: "tax-intake" do
     transition to: :extracted
   end
 
-  clarify :extracted do
+  extract :extracted do
     from :describe
     prompt "Extract: filing_status, dependents, income_types, state_filing."
     schema filing_status: :string,
@@ -241,7 +192,7 @@ definition = Inquirex.define id: "tax-intake" do
     skip_if not_empty(:dependents)
     transition to: :income_types
   end
-  # …and so on for every field in the clarify schema
+  # …and so on for every field in the extract schema
 end
 
 engine  = Inquirex::Engine.new(definition)
@@ -257,12 +208,7 @@ engine.prefill!(result)       # splats into top-level answers
 # whichever field the LLM couldn't fill in.
 ```
 
-`Engine#prefill!` is non-destructive (won't clobber an answer the user already
-gave), ignores `nil`/empty values so they don't spuriously trigger
-`not_empty`, and auto-advances past any step whose `skip_if` now evaluates
-true. See [examples/09_tax_preparer_llm.rb](../inquirex-tty/examples/09_tax_preparer_llm.rb)
-for a complete runnable flow, or the repo-level `demo_llm_intake.rb` for a
-scripted end-to-end walkthrough.
+`Engine#prefill!` is non-destructive (won't clobber an answer the user already gave), ignores `nil`/empty values so they don't spuriously trigger `not_empty`, and auto-advances past any step whose `skip_if` now evaluates true. See [examples/09_tax_preparer_llm.rb](../inquirex-tty/examples/09_tax_preparer_llm.rb) for a complete runnable flow, or the repo-level `demo_llm_intake.rb` for a scripted end-to-end walkthrough.
 
 ## JSON Serialization
 
@@ -270,9 +216,9 @@ LLM steps serialize with `"requires_server": true` so the JS widget knows to rou
 
 ```json
 {
-  "verb": "clarify",
+  "verb": "extract",
   "requires_server": true,
-  "transitions": [{ "to": "summary", "requires_server": true }],
+  "transitions": [{ "to": "next_step", "requires_server": true }],
   "llm": {
     "prompt": "Extract structured business information.",
     "schema": {
@@ -313,6 +259,47 @@ end
 
 The base class provides `#source_answers` (gathers relevant answers) and `#validate_output!` (checks schema conformance).
 
+## Future Possible LLM Verbs
+
+### `describe`
+
+Generate natural-language text from structured data. Requires `from` and `prompt`. No schema needed.
+
+```ruby
+describe :business_narrative do
+  from :business_extracted
+  prompt "Write a brief narrative of this business for the intake report."
+  transition to: :next_step
+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`.
+
+```ruby
+detour :followup do
+  from :description
+  prompt "Generate 2-3 follow-up questions to clarify the tax situation."
+  schema questions: :array, answers: :hash
+  transition to: :next_step
+end
+```
+
+## 
+
 ## Development
 
 ```bash
@@ -323,4 +310,8 @@ bundle exec rubocop
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+© 2026 Konstantin Gredeskoul.
+
+Distributed under the MIT License.
+
+See [LICENSE.txt](LICENSE.txt) for details.

data/docs/badges/coverage_badge.svg

@@ -15,7 +15,7 @@
   <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">99%</text>
-    <text x="80" y="14">99%</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,38 +1,69 @@
-set shell := ["bash", "-lc"]
+# Tell 'just' to run bash, source our setup script, then execute the recipe
+set shell := ["bash", "-c"]
 
-rbenv := 'eval "$(rbenv init -)"'
+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
+    just --choose
 
 # Sync all dependencies
 install:
-    {{rbenv}} && bin/setup
+    bin/setup
 
-# Lint and reformat files
-lint-fix *args:
-    {{rbenv}} && bundle exec rubocop -a
-
-alias format := lint-fix
+build: install
 
 # Lint and reformat files
 lint:
-    {{rbenv}} && bundle exec rubocop
+    {{ rbenv }} rubocop
+
+# Lint and reformat files (-a) — pass -A as an argument
+format *args:
+    {{ rbenv }} rubocop -a {{ args }}
 
 # Run all the tests
 test *args: 
-    {{rbenv}} &&  ENVIRONMENT=test bundle exec rspec {{args}}
+    export ENVIRONMENT=test; {{ rbenv }} rspec {{args}}
 
 # Run tests with coverage
 test-coverage *args:
-    ENVIRONMENT=test COVERAGE=true bundle exec rspec
+    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/*
+    @find . -name .DS_Store -delete -print || true
+    @rm -rf tmp/*
 
 # Run all lefthook pre-commit hooks
-ci:
-    {{rbenv}} && lefthook run pre-commit --all-files
+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/lib/inquirex/llm/adapter.rb

@@ -28,7 +28,7 @@ module Inquirex
       #
       # @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)
+      # @return [Hash, String] structured output (for extract) or text (when no schema)
       # @raise [Errors::AdapterError] if the LLM call fails
       # @raise [Errors::SchemaViolationError] if output doesn't match schema
       def call(node, answers)

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

@@ -5,7 +5,7 @@ module Inquirex
     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
+      # 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
@@ -15,34 +15,36 @@ module Inquirex
         # structured data matching the declared schema.
         #
         # @param id [Symbol] step id
-        def clarify(id, &)
-          add_llm_step(id, :clarify, &)
+        def extract(id, &)
+          add_llm_step(id, :extract, &)
         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
+        alias clarify extract
 
-        # 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 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 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
+        # # 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
 

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

@@ -8,7 +8,7 @@ module Inquirex
       # while inheriting transition and skip_if from the core StepBuilder.
       #
       # @example
-      #   clarify :business_extracted do
+      #   extract :business_extracted do
       #     from :business_description
       #     prompt "Extract structured business info."
       #     schema industry: :string, employee_count: :integer
@@ -112,7 +112,7 @@ module Inquirex
           @skip_if = rule
         end
 
-        # Optional display text (used by describe/summarize for user-visible labels).
+        # Optional display text (user-visible label for the step).
         #
         # @param content [String]
         def question(content)
@@ -159,15 +159,20 @@ module Inquirex
         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?
+          # Schema required for extract (and formerly detour).
+          if %i[extract].include?(@verb) && @schema_fields.empty?
+            # if %i[extract 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
+          return unless @from_steps.empty? && !@from_all
+          # 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)
+          # extract (and formerly describe/detour) should reference source steps or from_all
+          return unless %i[extract].include?(@verb)
+
+          # return unless %i[extract describe detour].include?(@verb)
 
           raise Errors::DefinitionError,
             "LLM step #{id.inspect} (#{@verb}) requires `from` or `from_all`"

data/lib/inquirex/llm/node.rb

@@ -7,16 +7,16 @@ module Inquirex
     # 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
+    #   :extract   — 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 schema [Schema, nil] expected output structure (required for extract)
     # @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)
@@ -24,7 +24,8 @@ 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[clarify describe summarize detour].freeze
+      LLM_VERBS = %i[extract].freeze
+      # LLM_VERBS = %i[extract describe summarize detour].freeze
 
       attr_reader :prompt,
         :schema,
@@ -89,7 +90,8 @@ module Inquirex
       # @param hash [Hash]
       # @return [LLM::Node]
       def self.from_h(id, hash)
-        verb             = hash["verb"]        || hash[:verb]
+        verb             = hash["verb"] || hash[:verb]
+        verb             = :extract if verb.to_s == "clarify" # DSL alias; normalize wire format
         question         = hash["question"]    || hash[:question]
         text             = hash["text"]        || hash[:text]
         transitions_data = hash["transitions"] || hash[:transitions] || []

data/lib/inquirex/llm/null_adapter.rb

@@ -5,13 +5,13 @@ module Inquirex
     # 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
+    # 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.
     #
     # @example
     #   adapter = Inquirex::LLM::NullAdapter.new
-    #   result = adapter.call(clarify_node, answers)
+    #   result = adapter.call(extract_node, answers)
     #   # => { industry: "", employee_count: 0, ... }
     class NullAdapter < Adapter
       TYPE_DEFAULTS = {

data/lib/inquirex/llm/version.rb

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

data/lib/inquirex/llm.rb

@@ -17,11 +17,11 @@ 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
+  # Extends the core DSL with LLM-powered verbs that run server-side:
+  #   - extract   — extract structured data from free-text answers (`clarify` is an alias)
+  #   # - 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.
@@ -33,7 +33,7 @@ module Inquirex
   #   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 }
+  #     extract(:extracted) { from :description; prompt "Extract info."; schema name: :string; transition to: :done }
   #     say(:done) { text "Done!" }
   #   end
   module LLM
@@ -41,5 +41,5 @@ module Inquirex
 end
 
 # Inject LLM verbs into the core FlowBuilder so that Inquirex.define
-# gains clarify/describe/summarize/detour when this gem is loaded.
+# gains extract (and clarify as an alias) when this gem is loaded.
 Inquirex::DSL::FlowBuilder.include(Inquirex::LLM::DSL::FlowBuilderExtension)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-llm
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -15,18 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-description: Extends the Inquirex DSL with four LLM-powered verbs — clarify, describe,
-  summarize, and detour — that run server-side to extract structured data, generate
-  text, and dynamically branch flows. Pluggable adapter interface keeps the gem LLM-agnostic;
-  a NullAdapter ships for testing.
+        version: '0.4'
+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
+  testing.'
 email:
 - kigster@gmail.com
 executables:
@@ -81,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: LLM integration verbs for the Inquirex questionnaire engine
 test_files: []