flowengine 0.3.1 → 0.4.1

data/examples/README.md

@@ -0,0 +1,14 @@
+# Examples from `bin/tax-estimate` script
+
+This folder does not have examples of the DSL (for that see the 
+gem sources for `flowengine-cli`).
+
+The script does not use the DSL and instead relies on a detailed system 
+prompt and an LLM to figure out what questions to answer, and uses
+it's understanding of the TTY::Prompt library to turn questions into
+ASCII-text based UI (TUI) type single/multi-select widgets, checkboxes
+or radio buttons.
+
+It's also an example of invoking LLM in a loop until the finishing 
+condition is satisfied.
+

data/examples/chat_history__complex.yml

@@ -0,0 +1,22 @@
+[
+  {"role":"llm","content":"What is your filing status?"},
+  {"role":"user","content":"Married Filing Jointly"},
+  {"role":"llm","content":"How many dependents are you claiming on your return?"},
+  {"role":"user","content":"1"},
+  {"role":"llm","content":"In how many states do you need to file a state tax return?"},
+  {"role":"user","content":"1 state"},
+  {"role":"llm","content":"What are your sources of income? (Select all that apply)"},
+  {"role":"user","content":["W-2 (wages from employer)"]},
+  {"role":"llm","content":"How many W-2s (employers) do you have in total between you and your spouse?"},
+  {"role":"user","content":"2"},
+  {"role":"llm","content":"Do you plan to itemize deductions, or will you take the standard deduction? Also, do you have any of the following credits or deductions? (Select all that apply)"},
+  {"role":"user","content":["Itemized deductions (mortgage interest, charitable contributions, etc.)","Child/dependent care credit"]},
+  {"role":"llm","content":"Do you have any of the following special situations? (Select all that apply)"},
+  {"role":"user","content":["Cryptocurrency transactions","Amended return needed"]},
+  {"role":"llm","content":"How would you describe your cryptocurrency transactions and records?"},
+  {"role":"user","content":"Moderate transactions (11-50), mostly organized"},
+  {"role":"llm","content":"Are you a new or returning client, and how would you describe the overall organization of your tax documents?"},
+  {"role":"user","content":"New client – documents somewhat disorganized"},
+  {"role":"llm","content":"Is there a deadline or rush requirement for your return?"},
+  {"role":"user","content":"No rush – standard timeline"}
+]

data/examples/chat_history__simple.yml

@@ -0,0 +1 @@
+[{"role":"llm","content":"Let's start with the basics. What is your filing status?"},{"role":"user","content":"Single"},{"role":"llm","content":"How many dependents are you claiming on your return?"},{"role":"user","content":"0"},{"role":"llm","content":"How many states do you need to file a return in?"},{"role":"user","content":"1 state"},{"role":"llm","content":"How many W-2s do you have, and do you have any other sources of income? (Select all that apply)"},{"role":"user","content":["W-2 (one employer)"]},{"role":"llm","content":"Do you have any of the following deductions or special tax situations? (Select all that apply)"},{"role":"user","content":[]},{"role":"llm","content":"Almost done! Do you have any of the following special situations or circumstances?"},{"role":"user","content":[]}]

data/examples/final_estimate__complex.yml

@@ -0,0 +1,58 @@
+---
+filing_status: Single
+dependents: 0
+states_required: 3 or more
+
+income_sources:
+  w2s: Multiple W-2s (2–3 employers)
+  self_employment: Yes (Schedule C)
+  business_entity: S-Corp or Partnership (separate entity return required)
+  capital_gains_stocks: Yes
+  rsu_iso_espp: Yes
+  cryptocurrency: Yes
+
+deductions_and_credits:
+  itemized_deductions: Yes (mortgage interest, charitable contributions, etc.)
+  business_expenses: Yes (home office, vehicle, meals, etc.)
+  foreign_income_or_accounts: Yes (FBAR / FATCA reporting required)
+  child_dependent_care_credits: Yes
+  irs_notices_or_amended_return: Yes
+
+business_factors:
+  entity_type: S-Corp or Partnership
+  depreciation_schedule: Yes
+  high_transaction_volume: Yes (50+ transactions)
+
+document_readiness:
+  records_status: Disorganized or incomplete (additional follow-up expected)
+  client_type: Not specified
+
+complexity_assessment:
+  score: 9.5 / 10
+  rationale: >
+    This return is extremely complex. It involves multiple states (3+), a separate
+    S-Corp or Partnership entity return, self-employment with high transaction volume
+    and depreciation, stock compensation (RSUs/ISOs/ESPP), cryptocurrency transactions,
+    capital gains, foreign income/FBAR/FATCA obligations, itemized deductions, business
+    expenses, an IRS notice or amended return, and disorganized records requiring
+    significant additional follow-up. Nearly every complexity factor is present.
+
+cost_estimate:
+  low: $4,500
+  high: $8,500
+  notes: >
+    The wide range reflects uncertainty due to disorganized records and the scope of
+    the S-Corp/Partnership entity return. The individual return alone (multi-state,
+    crypto, RSUs, FBAR, amended return) would typically run $2,500–$4,500. The
+    separate entity return (S-Corp or Partnership) adds $1,500–$3,000+. Disorganized
+    records and IRS notice resolution can add $500–$1,000 or more. Rush/deadline
+    fees may apply. A firm consultation is strongly recommended for a precise quote.
+
+recommendations:
+  - Engage a CPA or tax attorney experienced in international tax and equity compensation.
+  - Organize all records (bank statements, brokerage 1099s, crypto transaction logs)
+    before the engagement to minimize billable hours.
+  - File for an extension if needed to avoid rush fees.
+  - Ensure FBAR (FinCEN 114) and Form 8938 deadlines are tracked separately.
+  - Confirm whether the S-Corp/Partnership requires its own extension and estimated
+    tax payments.

data/examples/final_estimate__simple.yml

@@ -0,0 +1,50 @@
+---
+client_profile:
+  filing_status: Single
+  dependents: 0
+  states_required: 1
+
+income_sources:
+  w2_employers: 1
+  self_employment: false
+  rental_income: false
+  investment_income: false
+  retirement_distributions: false
+  foreign_income: false
+
+deductions_and_credits:
+  itemized_deductions: false
+  business_expenses: false
+  education_credits: false
+  energy_credits: false
+  child_dependent_care_credits: false
+
+special_situations:
+  stock_options: false
+  cryptocurrency: false
+  foreign_accounts: false
+  prior_year_carryforwards: false
+  amended_return: false
+  irs_notices: false
+
+complexity_assessment:
+  score: 1
+  out_of: 10
+  rationale: >
+    This is a straightforward return. Single filer, no dependents, one W-2 from a
+    single employer, one state return, no itemized deductions, no special income
+    sources, and no special situations. This is about as simple as a tax return
+    can get.
+
+cost_estimate:
+  low: $150
+  high: $300
+  average: $200
+  currency: USD
+  notes: >
+    Cost reflects a simple federal Form 1040 with a single W-2 and one state
+    return. Pricing may vary slightly based on the tax preparer's base rates and
+    whether the client is new or returning. Rush fees may apply if filing close
+    to the deadline.
+
+estimated_time_to_complete: 1-2 hours

data/lefthook.yml

@@ -0,0 +1,16 @@
+pre-commit:
+  parallel: true
+  jobs:
+    - name: format
+      glob: "*.{js,ts,tsx}"
+      run: npx biome format --write {staged_files}
+      stage_fixed: true
+
+    - name: rubocop
+      glob: "*.{rb,rake}"
+      run: bundle exec rubocop -a --format progress {staged_files}
+      staged_fixed: true
+
+    - name: rspecs
+      glob: "spec/**/*_spec.rb"
+      run: bundle exec rspec --format progress

data/lib/flowengine/llm/adapters/anthropic_adapter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    module Adapters
+      class AnthropicAdapter < Adapter
+        def self.api_key_var_name
+          "ANTHROPIC_API_KEY"
+        end
+
+        def self.default_model
+          "claude-sonnet-4-6"
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm/adapters/gemini_adapter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    module Adapters
+      class GeminiAdapter < Adapter
+        def self.api_key_var_name
+          "GEMINI_API_KEY"
+        end
+
+        def self.default_model
+          "gemini-2.5-flash"
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/llm/adapters/openai_adapter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FlowEngine
+  module LLM
+    module Adapters
+      class OpenAIAdapter < Adapter
+        def self.api_key_var_name
+          "OPENAI_API_KEY"
+        end
+
+        def self.default_model
+          "gpt-5-mini"
+        end
+      end
+    end
+  end
+end

data/lib/flowengine/version.rb

@@ -2,5 +2,5 @@
 
 module FlowEngine
   # Semantic version of the flowengine gem (major.minor.patch).
-  VERSION = "0.3.1"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -23,6 +23,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tty-box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -120,14 +148,24 @@ files:
 - ".env.example"
 - ".envrc"
 - ".rubocop_todo.yml"
+- Brewfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/PROJECT_STRUCTURE.md
 - docs/badges/coverage_badge.svg
-- docs/floweingine-architecture.png
+- docs/flowengine-architecture.png
 - docs/flowengine-example.png
+- docs/flowengine-processing.png
+- docs/tty-prompt.md
+- examples/README.md
+- examples/chat_history__complex.yml
+- examples/chat_history__simple.yml
+- examples/final_estimate__complex.yml
+- examples/final_estimate__simple.yml
 - exe/flowengine
 - justfile
+- lefthook.yml
 - lib/flowengine.rb
 - lib/flowengine/clarification_result.rb
 - lib/flowengine/definition.rb
@@ -144,6 +182,9 @@ files:
 - lib/flowengine/llm.rb
 - lib/flowengine/llm/adapter.rb
 - lib/flowengine/llm/adapters.rb
+- lib/flowengine/llm/adapters/anthropic_adapter.rb
+- lib/flowengine/llm/adapters/gemini_adapter.rb
+- lib/flowengine/llm/adapters/openai_adapter.rb
 - lib/flowengine/llm/auto_client.rb
 - lib/flowengine/llm/client.rb
 - lib/flowengine/llm/intake_prompt_builder.rb