inquirex-llm 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10d488773dcdef0cbf1f5fe93cdb916b7bf2bdf585e45d283b98fcda77dcd68d
-  data.tar.gz: 8c8128942112c74522f8f8c4e3be86904eeb5be510400f9c104f908ec24c7d5e
+  metadata.gz: 737239fae63381a1b7ab52afd9a811e6d57f4b781379c8dbaa694c7458e940a2
+  data.tar.gz: 531baf672a53604111e9799bdb2a1af4bfac01933a304589da6c68655db57dfb
 SHA512:
-  metadata.gz: a2ec2170b2fd8dd56bbfaa05ad3dd9507c6880ddce90993caa2af9519ccc002a869d87e0c784f855272480ffb1500f545152daeff0d5f29dcb9d9b68ffdb3849
-  data.tar.gz: 4f53ae8500c6cb8f11d89952f4b101a6fd919e3902e3d8bfed2b06fb0cb8b899b1fe93dfe309fddfb8e4c523b2b10d60d96551b9a2084efef09f118edaef197b
+  metadata.gz: 5a372a04fd14caddf249fd5b04d63f87508dc468ea50de016f57ac968814f4b8641fe96e6b05f05bc433a2c77978ffd120b4529a3ae5590867da46eb4e5f00e4
+  data.tar.gz: f8b604991408d6b61a063a9f337e32fe8de96c0de5b6eda7bf08dfe496f19756833abae6c3437cf6078c9efe5ff5230c05f14f3b0ea2e205b68c9efc8d7bb416

data/.rubocop_todo.yml

@@ -0,0 +1,28 @@
+# 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/README.md

@@ -159,6 +159,111 @@ result = adapter.call(engine.current_step)
 # => { industry: "", employee_count: 0, revenue: 0.0 }
 ```
 
+## 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` |
+
+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.
+
+### AnthropicAdapter
+
+```ruby
+adapter = Inquirex::LLM::AnthropicAdapter.new(
+  api_key: ENV["ANTHROPIC_API_KEY"],
+  model:   "claude-sonnet-4-20250514"   # or pass the short symbol in the DSL
+)
+```
+
+Recognized `model :symbol` values in the DSL: `:claude_sonnet`,
+`:claude_haiku`, `:claude_opus` (mapped to the current concrete model ids).
+
+### OpenAIAdapter
+
+```ruby
+adapter = Inquirex::LLM::OpenAIAdapter.new(
+  api_key: ENV["OPENAI_API_KEY"],
+  model:   "gpt-4o-mini"
+)
+```
+
+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:
+
+```ruby
+definition = Inquirex.define id: "tax-intake" do
+  start :describe
+
+  ask :describe do
+    type :text
+    question "Describe your 2025 tax situation."
+    transition to: :extracted
+  end
+
+  clarify :extracted do
+    from :describe
+    prompt "Extract: filing_status, dependents, income_types, state_filing."
+    schema filing_status: :string,
+           dependents:    :integer,
+           income_types:  :multi_enum,
+           state_filing:  :string
+    model :claude_sonnet
+    transition to: :filing_status
+  end
+
+  ask :filing_status do
+    type :enum
+    question "Filing status?"
+    options %w[single married_filing_jointly head_of_household]
+    skip_if not_empty(:filing_status)     # ← the whole trick
+    transition to: :dependents
+  end
+
+  ask :dependents do
+    type :integer
+    question "How many dependents?"
+    skip_if not_empty(:dependents)
+    transition to: :income_types
+  end
+  # …and so on for every field in the clarify schema
+end
+
+engine  = Inquirex::Engine.new(definition)
+adapter = Inquirex::LLM::OpenAIAdapter.new  # or AnthropicAdapter
+
+engine.answer("I'm MFJ with two kids in California, W-2 plus some crypto.")
+result = adapter.call(engine.current_step, engine.answers)
+engine.answer(result)         # stored under :extracted
+engine.prefill!(result)       # splats into top-level answers
+
+# Every downstream step whose skip_if rule now evaluates true gets
+# auto-skipped by the engine. engine.current_step_id jumps straight to
+# 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.
+
 ## 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:

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">98%</text>
-    <text x="80" y="14">98%</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">99%</text>
+    <text x="80" y="14">99%</text>
   </g>
 </svg>

data/lib/inquirex/llm/anthropic_adapter.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "inquirex/llm/adapter"
+
+module Inquirex
+  module LLM
+    # Real Anthropic Claude adapter for inquirex-llm.
+    #
+    # Usage:
+    #   adapter = Inquirex::LLM::AnthropicAdapter.new(
+    #     api_key: ENV["ANTHROPIC_API_KEY"],
+    #     model:   "claude-sonnet-4-20250514"
+    #   )
+    #   result = adapter.call(engine.current_step, engine.answers)
+    #
+    # The adapter:
+    #   1. Gathers source answers from the step's `from` / `from_all` declaration
+    #   2. Builds a prompt that includes the schema as a JSON contract
+    #   3. Calls the Anthropic Messages API
+    #   4. Parses the JSON response
+    #   5. Validates output against the declared schema
+    #   6. Returns the structured hash
+    class AnthropicAdapter < Adapter
+      API_URL = "https://api.anthropic.com/v1/messages"
+      API_VERSION = "2023-06-01"
+      DEFAULT_MODEL = "claude-sonnet-4-20250514"
+      DEFAULT_MAX_TOKENS = 2048
+
+      # Maps Inquirex short model symbols to concrete Anthropic model ids.
+      MODEL_MAP = {
+        claude_sonnet: "claude-sonnet-4-20250514",
+        claude_haiku:  "claude-haiku-4-5-20251001",
+        claude_opus:   "claude-opus-4-20250514"
+      }.freeze
+
+      # @param api_key [String, nil] defaults to ENV["ANTHROPIC_API_KEY"]
+      # @param model   [String, nil] default model id when a node does not specify one
+      def initialize(api_key: nil, model: nil)
+        super()
+        @api_key = api_key || ENV.fetch("ANTHROPIC_API_KEY") {
+          raise ArgumentError, "ANTHROPIC_API_KEY is required (pass api_key: or set the env var)"
+        }
+        @default_model = model || DEFAULT_MODEL
+      end
+
+      # @param node [Inquirex::LLM::Node] the current LLM step
+      # @param answers [Hash] all collected answers so far
+      # @return [Hash] structured data matching the node's schema
+      # @raise [Errors::AdapterError] on API / parse failures
+      # @raise [Errors::SchemaViolationError] when the LLM output misses schema fields
+      def call(node, answers = {})
+        source      = source_answers(node, answers)
+        model       = resolve_model(node)
+        temperature = node.respond_to?(:temperature) ? (node.temperature || 0.2) : 0.2
+        max_tokens  = node.respond_to?(:max_tokens)  ? (node.max_tokens  || DEFAULT_MAX_TOKENS) : DEFAULT_MAX_TOKENS
+
+        response = call_api(
+          model:       model,
+          system:      build_system_prompt(node),
+          user:        build_user_prompt(node, source, answers),
+          temperature: temperature,
+          max_tokens:  max_tokens
+        )
+
+        result = parse_response(response)
+        validate_output!(node, result)
+        result
+      end
+
+      private
+
+      def resolve_model(node)
+        return @default_model unless node.respond_to?(:model) && node.model
+
+        MODEL_MAP[node.model.to_sym] || node.model.to_s
+      end
+
+      def build_system_prompt(node)
+        "You are a data extraction assistant for a questionnaire engine. " \
+        "Your job is to analyze user input and extract structured data." +
+          schema_instruction(node)
+      end
+
+      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" \
+            "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. " \
+            "No markdown fences. Just the raw JSON object."
+        end
+      end
+
+      def build_user_prompt(node, source, all_answers)
+        parts = []
+        parts << "Task: #{node.prompt}" if node.respond_to?(:prompt) && node.prompt
+
+        if source.is_a?(Hash) && source.any?
+          parts << "\nSource data from previous answers:"
+          source.each { |key, value| parts << "  #{key}: #{value.inspect}" }
+        end
+
+        if node.respond_to?(:schema) && node.schema
+          parts << "\nExtract these fields from the source data:"
+          node.schema.fields.each { |field, type| parts << "  #{field} (#{type})" }
+        end
+
+        if node.respond_to?(:from_all) && node.from_all && all_answers.any?
+          parts << "\nAll collected answers:"
+          all_answers.each { |key, value| parts << "  #{key}: #{value.inspect}" }
+        end
+
+        parts.join("\n")
+      end
+
+      def call_api(model:, system:, user:, temperature:, max_tokens:)
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 30
+        http.open_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"]      = "application/json"
+        request["x-api-key"]         = @api_key
+        request["anthropic-version"] = API_VERSION
+        request.body = JSON.generate(
+          model:       model,
+          max_tokens:  max_tokens,
+          temperature: temperature,
+          system:      system,
+          messages:    [{ role: "user", content: user }]
+        )
+
+        warn "[inquirex-llm] Calling #{model}..." if ENV["INQUIREX_DEBUG"]
+
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Errors::AdapterError, "Anthropic API error #{response.code}: #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def parse_response(api_response)
+        content    = api_response["content"]
+        text_block = content.is_a?(Array) ? content.find { |c| c["type"] == "text" } : nil
+        raise Errors::AdapterError, "No text content in Anthropic response" unless text_block
+
+        raw_text = text_block["text"].to_s.strip
+        raw_text = raw_text.gsub(/\A```(?:json)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
+
+        parsed = JSON.parse(raw_text, symbolize_names: true)
+        raise Errors::AdapterError, "Expected JSON object from LLM, got #{parsed.class}" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Errors::AdapterError,
+          "Failed to parse LLM response as JSON: #{e.message}\nRaw: #{raw_text.inspect}"
+      end
+    end
+  end
+end

data/lib/inquirex/llm/openai_adapter.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "inquirex/llm/adapter"
+
+module Inquirex
+  module LLM
+    # OpenAI Chat Completions adapter for inquirex-llm.
+    #
+    # Uses the Chat Completions API with response_format: { type: "json_object" }
+    # so the model is constrained to return a valid JSON object — more reliable
+    # than prompt-only "please return JSON" approaches for structured extraction.
+    #
+    # Usage:
+    #   adapter = Inquirex::LLM::OpenAIAdapter.new(
+    #     api_key: ENV["OPENAI_API_KEY"],
+    #     model:   "gpt-4o-mini"
+    #   )
+    #   result = adapter.call(engine.current_step, engine.answers)
+    class OpenAIAdapter < Adapter
+      API_URL = "https://api.openai.com/v1/chat/completions"
+      DEFAULT_MODEL = "gpt-4o-mini"
+      DEFAULT_MAX_TOKENS = 2048
+
+      # Maps Inquirex DSL model symbols to concrete OpenAI model ids. Accepts
+      # Claude symbols too — we substitute sensible OpenAI equivalents so flow
+      # definitions written against Anthropic still run against this adapter.
+      MODEL_MAP = {
+        gpt_4o:        "gpt-4o",
+        gpt_4o_mini:   "gpt-4o-mini",
+        gpt_4_1:       "gpt-4.1",
+        gpt_4_1_mini:  "gpt-4.1-mini",
+        claude_sonnet: "gpt-4o",
+        claude_haiku:  "gpt-4o-mini",
+        claude_opus:   "gpt-4o"
+      }.freeze
+
+      # @param api_key [String, nil] defaults to ENV["OPENAI_API_KEY"]
+      # @param model   [String, nil] default model id when a node does not specify one
+      def initialize(api_key: nil, model: nil)
+        super()
+        @api_key = api_key || ENV.fetch("OPENAI_API_KEY") {
+          raise ArgumentError, "OPENAI_API_KEY is required (pass api_key: or set the env var)"
+        }
+        @default_model = model || DEFAULT_MODEL
+      end
+
+      # @param node [Inquirex::LLM::Node] the current LLM step
+      # @param answers [Hash] all collected answers so far
+      # @return [Hash] structured data matching the node's schema
+      # @raise [Errors::AdapterError] on API / parse failures
+      # @raise [Errors::SchemaViolationError] when the LLM output misses schema fields
+      def call(node, answers = {})
+        source      = source_answers(node, answers)
+        model       = resolve_model(node)
+        temperature = node.respond_to?(:temperature) ? (node.temperature || 0.2) : 0.2
+        max_tokens  = node.respond_to?(:max_tokens)  ? (node.max_tokens  || DEFAULT_MAX_TOKENS) : DEFAULT_MAX_TOKENS
+
+        response = call_api(
+          model:       model,
+          system:      build_system_prompt(node),
+          user:        build_user_prompt(node, source, answers),
+          temperature: temperature,
+          max_tokens:  max_tokens
+        )
+
+        result = parse_response(response)
+        validate_output!(node, result)
+        result
+      end
+
+      private
+
+      def resolve_model(node)
+        return @default_model unless node.respond_to?(:model) && node.model
+
+        MODEL_MAP[node.model.to_sym] || node.model.to_s
+      end
+
+      def build_system_prompt(node)
+        "You are a data extraction assistant for a questionnaire engine. " \
+        "Your job is to analyze user input and extract structured data. " \
+        "You MUST respond with a single valid JSON object and nothing else." +
+          schema_instruction(node)
+      end
+
+      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" \
+            "Every key in the schema must be present in your output. Use null, \"\", 0, or [] " \
+            "for values the source text does not provide."
+        else
+          ""
+        end
+      end
+
+      def build_user_prompt(node, source, all_answers)
+        parts = []
+        parts << "Task: #{node.prompt}" if node.respond_to?(:prompt) && node.prompt
+
+        if source.is_a?(Hash) && source.any?
+          parts << "\nSource data from previous answers:"
+          source.each { |key, value| parts << "  #{key}: #{value.inspect}" }
+        end
+
+        if node.respond_to?(:schema) && node.schema
+          parts << "\nExtract these fields as a JSON object:"
+          node.schema.fields.each { |field, type| parts << "  #{field} (#{type})" }
+        end
+
+        if node.respond_to?(:from_all) && node.from_all && all_answers.any?
+          parts << "\nAll collected answers:"
+          all_answers.each { |key, value| parts << "  #{key}: #{value.inspect}" }
+        end
+
+        parts << "\nReturn ONLY the JSON object."
+        parts.join("\n")
+      end
+
+      def call_api(model:, system:, user:, temperature:, max_tokens:)
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 30
+        http.open_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"]  = "application/json"
+        request["Authorization"] = "Bearer #{@api_key}"
+        request.body = JSON.generate(
+          model:           model,
+          max_tokens:      max_tokens,
+          temperature:     temperature,
+          response_format: { type: "json_object" },
+          messages:        [
+            { role: "system", content: system },
+            { role: "user",   content: user }
+          ]
+        )
+
+        warn "[inquirex-llm] Calling OpenAI #{model}..." if ENV["INQUIREX_DEBUG"]
+
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Errors::AdapterError, "OpenAI API error #{response.code}: #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def parse_response(api_response)
+        choices = api_response["choices"]
+        message = choices.is_a?(Array) ? choices.first&.dig("message") : nil
+        raw_text = message&.dig("content")
+        raise Errors::AdapterError, "No message content in OpenAI response" unless raw_text
+
+        raw_text = raw_text.to_s.strip
+        raw_text = raw_text.gsub(/\A```(?:json)?\s*\n?/, "").gsub(/\n?```\s*\z/, "").strip
+
+        parsed = JSON.parse(raw_text, symbolize_names: true)
+        raise Errors::AdapterError, "Expected JSON object from LLM, got #{parsed.class}" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Errors::AdapterError,
+          "Failed to parse LLM response as JSON: #{e.message}\nRaw: #{raw_text.inspect}"
+      end
+    end
+  end
+end

data/lib/inquirex/llm/version.rb

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

data/lib/inquirex/llm.rb

@@ -9,6 +9,8 @@ require_relative "llm/schema"
 require_relative "llm/node"
 require_relative "llm/adapter"
 require_relative "llm/null_adapter"
+require_relative "llm/anthropic_adapter"
+require_relative "llm/openai_adapter"
 require_relative "llm/dsl/llm_step_builder"
 require_relative "llm/dsl/flow_builder"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-llm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -35,6 +35,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".relaxed_rubocop.yml"
+- ".rubocop_todo.yml"
 - ".secrets.baseline"
 - CHANGELOG.md
 - LICENSE.txt
@@ -47,11 +48,13 @@ files:
 - lib/inquirex-llm.rb
 - lib/inquirex/llm.rb
 - lib/inquirex/llm/adapter.rb
+- lib/inquirex/llm/anthropic_adapter.rb
 - lib/inquirex/llm/dsl/flow_builder.rb
 - lib/inquirex/llm/dsl/llm_step_builder.rb
 - lib/inquirex/llm/errors.rb
 - lib/inquirex/llm/node.rb
 - lib/inquirex/llm/null_adapter.rb
+- lib/inquirex/llm/openai_adapter.rb
 - lib/inquirex/llm/schema.rb
 - lib/inquirex/llm/version.rb
 - sig/inquirex/llm.rbs