inquirex-llm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10d488773dcdef0cbf1f5fe93cdb916b7bf2bdf585e45d283b98fcda77dcd68d
+  data.tar.gz: 8c8128942112c74522f8f8c4e3be86904eeb5be510400f9c104f908ec24c7d5e
+SHA512:
+  metadata.gz: a2ec2170b2fd8dd56bbfaa05ad3dd9507c6880ddce90993caa2af9519ccc002a869d87e0c784f855272480ffb1500f545152daeff0d5f29dcb9d9b68ffdb3849
+  data.tar.gz: 4f53ae8500c6cb8f11d89952f4b101a6fd919e3902e3d8bfed2b06fb0cb8b899b1fe93dfe309fddfb8e4c523b2b10d60d96551b9a2084efef09f118edaef197b

data/.relaxed_rubocop.yml

@@ -0,0 +1,153 @@
+# 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/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "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/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-13
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Konstantin Gredeskoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+[![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.
+
+## Status
+
+- Version: `0.1.0`
+- Ruby: `>= 4.0.0`
+- Test suite: `111 examples, 0 failures`
+- Depends on: `inquirex` (core gem)
+
+## Installation
+
+```ruby
+gem "inquirex-llm"
+```
+
+## Usage
+
+`require "inquirex-llm"` injects the LLM verbs into the core `Inquirex.define` DSL. No separate entry point needed.
+
+```ruby
+require "inquirex"
+require "inquirex-llm"
+
+definition = Inquirex.define id: "tax-intake-2026", version: "1.0.0" do
+  start :description
+
+  ask :description do
+    type :text
+    question "Describe your business in a few sentences."
+    transition to: :extracted
+  end
+
+  clarify :extracted do
+    from :description
+    prompt "Extract structured business information from the description."
+    schema industry:          :string,
+           entity_type:       :string,
+           employee_count:    :integer,
+           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
+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
+
+### `clarify`
+
+Extract structured data from a free-text answer. Requires `from`, `prompt`, and `schema`.
+
+```ruby
+clarify :business_extracted do
+  from :business_description
+  prompt "Extract structured business information."
+  schema industry: :string, employee_count: :integer, revenue: :currency
+  model :claude_sonnet
+  temperature 0.2
+  max_tokens 1024
+  transition to: :next_step
+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 |
+
+## Engine Integration
+
+The engine treats LLM steps as collecting steps. The server adapter processes the LLM call and feeds the result back:
+
+```ruby
+engine = Inquirex::Engine.new(definition)
+
+engine.answer("I run an LLC with 15 employees, ~$2M revenue.")
+# engine.current_step_id => :extracted
+
+# Server-side: adapter calls the LLM
+adapter = MyLlmAdapter.new
+result = adapter.call(engine.current_step, engine.answers)
+# => { industry: "Technology", employee_count: 15, revenue: 2_000_000.0 }
+
+engine.answer(result)
+# engine.current_step_id => :summary
+```
+
+For testing, use `NullAdapter` which returns schema-conformant placeholder values without any API calls:
+
+```ruby
+adapter = Inquirex::LLM::NullAdapter.new
+result = adapter.call(engine.current_step)
+# => { industry: "", employee_count: 0, revenue: 0.0 }
+```
+
+## JSON Serialization
+
+LLM steps serialize with `"requires_server": true` so the JS widget knows to round-trip to the server. LLM metadata lives under an `"llm"` key:
+
+```json
+{
+  "verb": "clarify",
+  "requires_server": true,
+  "transitions": [{ "to": "summary", "requires_server": true }],
+  "llm": {
+    "prompt": "Extract structured business information.",
+    "schema": {
+      "industry": "string",
+      "employee_count": "integer",
+      "revenue": "currency"
+    },
+    "from_steps": ["business_description"],
+    "model": "claude_sonnet",
+    "temperature": 0.2,
+    "max_tokens": 1024
+  }
+}
+```
+
+Fallback procs are stripped from JSON (server-side only).
+
+## Custom Adapter
+
+Subclass `Inquirex::LLM::Adapter` and implement `#call(node, answers)`:
+
+```ruby
+class MyLlmAdapter < Inquirex::LLM::Adapter
+  def call(node, answers)
+    source = source_answers(node, answers)
+    response = my_llm_client.complete(
+      node.prompt,
+      context: source,
+      model: node.model,
+      temperature: node.temperature
+    )
+    result = parse_response(response)
+    validate_output!(node, result)
+    result
+  end
+end
+```
+
+The base class provides `#source_answers` (gathers relevant answers) and `#validate_output!` (checks schema conformance).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,21 @@
+<?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/exe/inquirex-llm

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "inquirex/llm"

data/justfile

@@ -0,0 +1,38 @@
+set shell := ["bash", "-lc"]
+
+rbenv := 'eval "$(rbenv init -)"'
+
+[no-exit-message]
+recipes:
+    @just --choose
+
+# Sync all dependencies
+install:
+    {{rbenv}} && bin/setup
+
+# Lint and reformat files
+lint-fix *args:
+    {{rbenv}} && bundle exec rubocop -a
+
+alias format := lint-fix
+
+# Lint and reformat files
+lint:
+    {{rbenv}} && bundle exec rubocop
+
+# Run all the tests
+test *args: 
+    {{rbenv}} &&  ENVIRONMENT=test bundle exec rspec {{args}}
+
+# Run tests with coverage
+test-coverage *args:
+    ENVIRONMENT=test COVERAGE=true bundle exec rspec
+
+clean:
+    #!/usr/bin/env bash
+    find . -name .DS_Store -delete -print || true
+    rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+ci:
+    {{rbenv}} && lefthook run pre-commit --all-files

data/lefthook.yml

@@ -0,0 +1,35 @@
+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