inquirex-tty 0.4.0

data/examples/08_tax_preparer.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# Example 8: Tax Preparer Intake
+#
+# The most complex example — 18+ steps with multi-level branching,
+# enum selections, boolean gates, and free-text collection.
+# Demonstrates a real-world intake wizard for a tax preparation service.
+#
+# Note: The original flowengine example used number_matrix for collecting
+# structured numeric data (business types, rental property counts). Inquirex
+# uses :string steps for those sections since number_matrix is not part of
+# the Inquirex DSL. All rule logic is preserved.
+#
+# Run:  bundle exec exe/inquirex-tty run examples/08_tax_preparer.rb
+
+Inquirex.define id: "tax-preparer-2025", version: "1.0.0" do
+  meta title: "Tax Preparation Intake",
+    subtitle: "Help us understand your tax situation"
+
+  start :intro
+
+  # Opening instructions (no input collected)
+  say :intro do
+    text "Please describe your tax situation in a few sentences.\n" \
+         "Do not under any circumstances provide personal information,\n" \
+         "such as your address or social security number.\n\n" \
+         "Example: I have two W-2s from my two jobs, a rental property, " \
+         "and a side business."
+    transition to: :filing_status
+  end
+
+  ask :filing_status do
+    type :enum
+    question "What is your filing status for 2025?"
+    options({
+      "single"                    => "Single",
+      "married_filing_jointly"    => "Married Filing Jointly",
+      "married_filing_separately" => "Married Filing Separately",
+      "head_of_household"         => "Head of Household",
+      "widowed"                   => "Widowed"
+    })
+    widget target: :tty,     type: :select
+    widget target: :desktop, type: :radio_group, columns: 1
+    widget target: :mobile,  type: :dropdown
+    transition to: :dependents
+  end
+
+  ask :dependents do
+    type :integer
+    question "How many dependents do you have?"
+    widget target: :tty, type: :number_input
+    default 0
+    transition to: :income_types
+  end
+
+  ask :income_types do
+    type :multi_enum
+    question "Select all income types that apply to you in 2025."
+    options %w[W2 1099 Business Investment Rental Retirement]
+    widget target: :tty,     type: :multi_select
+    widget target: :desktop, type: :checkbox_group
+    transition to: :business_count,      if_rule: contains(:income_types, "Business")
+    transition to: :investment_details,  if_rule: contains(:income_types, "Investment")
+    transition to: :rental_details,      if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  ask :business_count do
+    type :integer
+    question "How many total businesses do you own or are a partner in?"
+    widget target: :tty, type: :number_input
+    transition to: :complex_business_info, if_rule: greater_than(:business_count, 2)
+    transition to: :business_details
+  end
+
+  ask :complex_business_info do
+    type :text
+    question "With more than 2 businesses, please provide your primary EIN " \
+             "and a brief description of each entity."
+    widget target: :tty, type: :multiline
+    transition to: :business_details
+  end
+
+  # Collect counts for each business type (RealEstate, SCorp, CCorp, Trust, LLC)
+  ask :business_details do
+    type :string
+    question "How many of each business type do you own? " \
+             "(RealEstate, SCorp, CCorp, Trust, LLC — enter comma-separated counts)"
+    widget target: :tty, type: :text_input
+    transition to: :investment_details, if_rule: contains(:income_types, "Investment")
+    transition to: :rental_details,     if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  ask :investment_details do
+    type :multi_enum
+    question "What types of investments do you hold?"
+    options %w[Stocks Bonds Crypto RealEstate MutualFunds]
+    widget target: :tty,     type: :multi_select
+    widget target: :desktop, type: :checkbox_group
+    transition to: :crypto_details,   if_rule: contains(:investment_details, "Crypto")
+    transition to: :rental_details,   if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  ask :crypto_details do
+    type :text
+    question "Please describe your cryptocurrency transactions " \
+             "(exchanges used, approximate number of transactions)."
+    widget target: :tty, type: :multiline
+    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
+    transition to: :state_filing
+  end
+
+  # Collect counts for each rental property type (Residential, Commercial, Vacation)
+  ask :rental_details do
+    type :string
+    question "How many rental properties of each type do you own? " \
+             "(Residential, Commercial, Vacation — enter comma-separated counts)"
+    widget target: :tty, type: :text_input
+    transition to: :state_filing
+  end
+
+  ask :state_filing do
+    type :multi_enum
+    question "Which states do you need to file in?"
+    options %w[California NewYork Texas Florida Illinois Other]
+    widget target: :tty,     type: :multi_select
+    widget target: :desktop, type: :checkbox_group
+    transition to: :foreign_accounts
+  end
+
+  ask :foreign_accounts do
+    type :enum
+    question "Do you have any foreign financial accounts " \
+             "(bank accounts, securities, or financial assets)?"
+    options %w[yes no]
+    widget target: :tty,     type: :select
+    widget target: :desktop, type: :radio_group
+    transition to: :foreign_account_details, if_rule: equals(:foreign_accounts, "yes")
+    transition to: :deduction_types
+  end
+
+  ask :foreign_account_details do
+    type :integer
+    question "How many foreign accounts do you have?"
+    widget target: :tty, type: :number_input
+    transition to: :deduction_types
+  end
+
+  ask :deduction_types do
+    type :multi_enum
+    question "Which additional deductions apply to you?"
+    options %w[Medical Charitable Education Mortgage None]
+    widget target: :tty,     type: :multi_select
+    widget target: :desktop, type: :checkbox_group
+    transition to: :charitable_amount, if_rule: contains(:deduction_types, "Charitable")
+    transition to: :client_name
+  end
+
+  ask :charitable_amount do
+    type :currency
+    question "How much did you donate to charity in 2025?"
+    widget target: :tty, type: :number_input
+    transition to: :charitable_documentation, if_rule: greater_than(:charitable_amount, 5000)
+    transition to: :client_name
+  end
+
+  ask :charitable_documentation do
+    type :text
+    question "For charitable contributions over $5,000, please describe " \
+             "what sort of paperwork you have available."
+    widget target: :tty, type: :multiline
+    transition to: :client_name
+  end
+
+  ask :client_name do
+    type :string
+    question "Your name, please:"
+    widget target: :tty, type: :text_input
+    transition to: :client_email
+  end
+
+  ask :client_email do
+    type :email
+    question "Your email address:"
+    widget target: :tty, type: :text_input
+    transition to: :thanks
+  end
+
+  say :thanks do
+    text "Thank you! We will review your information and send you " \
+         "a tax preparation estimate within 1-2 business days."
+  end
+end

data/examples/09_tax_preparer_llm.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Example 09: Tax Preparer Intake with LLM-assisted pre-fill
+#
+# The thesis:
+#   "Deterministic DSL defines what data you need.
+#    LLM extracts what it can from one free-text answer.
+#    The engine only asks what's left."
+#
+# Flow:
+#   1. :describe      — one open-ended question
+#   2. :extracted     — clarify step; LLM returns structured fields
+#   3. :filing_status, :dependents, :income_types, :state_filing, :client_contact
+#                     — asked only when the LLM left the field blank
+#   4. :summary       — LLM produces a complexity / fee summary over everything
+#   5. :done          — farewell
+#
+# Run:
+#   bundle exec exe/inquirex-tty run examples/09_tax_preparer_llm.rb
+#
+# Uses ANTHROPIC_API_KEY from .env (or any parent .env) for live Claude calls.
+# Falls back to Inquirex::LLM::NullAdapter when the key is absent, or when
+# INQUIREX_LLM_ADAPTER=null is set.
+
+require "inquirex"
+require "inquirex/llm"
+
+Inquirex.define id: "tax-preparer-llm-2025", version: "1.0.0" do
+  meta title: "Tax Prep Intake (LLM-assisted)",
+    subtitle: "Tell us about your tax situation — we'll only ask what we can't figure out"
+
+  start :describe
+
+  ask :describe do
+    type :text
+    question "Please describe your 2025 tax situation in your own words.\n" \
+             "Mention filing status, kids/dependents, income sources\n" \
+             "(W-2, business, rental, investments, crypto), and your state.\n" \
+             "Do NOT include SSN or home address."
+    widget target: :tty, type: :multiline
+    transition to: :extracted
+  end
+
+  clarify :extracted do
+    from :describe
+    prompt <<~PROMPT
+      You are a tax-prep intake assistant. Extract structured information from
+      the client's free-text description.
+
+      STRICT VALUE RULES — you MUST use these exact string literals, no others:
+
+      filing_status: exactly ONE of:
+        "single" | "married_filing_jointly" | "married_filing_separately"
+        | "head_of_household" | "widowed"
+      Use "" (empty string) if the client did not indicate a filing status.
+
+      dependents: integer count of dependents (0 if client said they have none;
+      null only if the client made no mention of dependents at all).
+
+      income_types: array. Each element MUST be ONE of these exact tokens
+      (case-sensitive, no hyphens, no spaces, no variants):
+        "W2"          — W-2 employment / regular salary / wage job
+        "1099"        — 1099 contracting / freelance / gig work
+        "Business"    — self-employment, LLC, S-corp, C-corp, sole-prop, partnership, consulting business
+        "Investment"  — stocks, bonds, crypto, mutual funds, dividends, capital gains
+        "Rental"      — rental property income (residential, commercial, or vacation)
+        "Retirement"  — 401(k), IRA, pension, social-security income
+      Do NOT output "W-2", "self-employment", "self_employment", "rental income",
+      "investments", or any variant — use only the tokens listed above.
+      Use [] if the client mentioned no income types.
+
+      state_filing: the primary US state as a capitalized English name
+      ("California", "New York", "Texas"). Use "" if unmentioned.
+
+      IMPORTANT: Only include a value when the client's text gives you concrete
+      evidence. Do NOT infer or guess. Use null / "" / [] liberally.
+    PROMPT
+    schema filing_status: :string,
+      dependents:    :integer,
+      income_types:  :multi_enum,
+      state_filing:  :string
+    model :claude_sonnet
+    temperature 0.0
+    transition to: :filing_status
+  end
+
+  ask :filing_status do
+    type :enum
+    question "What is your filing status for 2025?"
+    options({
+      "single"                    => "Single",
+      "married_filing_jointly"    => "Married Filing Jointly",
+      "married_filing_separately" => "Married Filing Separately",
+      "head_of_household"         => "Head of Household",
+      "widowed"                   => "Widowed"
+    })
+    widget target: :tty, type: :select
+    skip_if not_empty(:filing_status)
+    transition to: :dependents
+  end
+
+  ask :dependents do
+    type :integer
+    question "How many dependents do you have?"
+    widget target: :tty, type: :number_input
+    default 0
+    skip_if not_empty(:dependents)
+    transition to: :income_types
+  end
+
+  ask :income_types do
+    type :multi_enum
+    question "Select all income types that apply to you in 2025."
+    options %w[W2 1099 Business Investment Rental Retirement]
+    widget target: :tty, type: :multi_select
+    skip_if not_empty(:income_types)
+    transition to: :state_filing
+  end
+
+  ask :state_filing do
+    type :string
+    question "Which state do you need to file in?"
+    widget target: :tty, type: :text_input
+    skip_if not_empty(:state_filing)
+    transition to: :client_contact
+  end
+
+  ask :client_contact do
+    type :string
+    question "Your name and email (so we can send the quote)?"
+    widget target: :tty, type: :text_input
+    transition to: :summary
+  end
+
+  summarize :summary do
+    from_all
+    prompt <<~PROMPT
+      Based on the collected answers, produce a concise JSON object with:
+        - complexity: "simple" | "moderate" | "complex"
+        - fee_estimate_low:  integer USD
+        - fee_estimate_high: integer USD
+        - red_flags: array of short strings (empty array if none)
+        - notes: one-sentence summary for the preparer
+    PROMPT
+    transition to: :done
+  end
+
+  say :done do
+    text "Thank you! A tax professional will review your intake and reach out."
+  end
+end

data/examples/10_answers.json

@@ -0,0 +1,53 @@
+{
+  "flow_file": "examples/10_real_tax_preparer.rb",
+  "path_taken": [
+    "intro",
+    "residency_status",
+    "prior_return_available",
+    "filing_status",
+    "dependents_band",
+    "income_types",
+    "w2_count",
+    "state_filing",
+    "state_residency",
+    "foreign_accounts",
+    "surprise_heads_up",
+    "tax_notices",
+    "estimated_payments",
+    "deduction_types",
+    "timeline",
+    "client_email",
+    "thanks"
+  ],
+  "answers": {
+    "residency_status": "us_person",
+    "prior_return_available": "yes_last_year",
+    "filing_status": "married_filing_jointly",
+    "dependents_band": "2",
+    "income_types": [
+      "W2",
+      "1099_nec",
+      "1099_k"
+    ],
+    "w2_count": "2",
+    "state_filing": [
+      "CA",
+      "CO"
+    ],
+    "state_residency": "multi",
+    "foreign_accounts": "no",
+    "tax_notices": [
+      "state_notice"
+    ],
+    "estimated_payments": "none",
+    "deduction_types": [
+      "mortgage",
+      "salt",
+      "hsa_fsa"
+    ],
+    "timeline": "asap",
+    "client_email": "kigster@gmail.com"
+  },
+  "steps_completed": 17,
+  "completed_at": "2026-04-14T16:08:16-07:00"
+}