flowengine 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abf9fcf3a78e2d13e003360a8dbce3ab2c21a2f7b30ff7d0d45e890d70ac1a65
-  data.tar.gz: 958fce5978e1724238d4a109efe37f11be5e4885e9f723563262aea2434da0b1
+  metadata.gz: 44af196ec2b3b9611c304c0ad30c8bbd600d679657e9e91990a17c23a10ca13c
+  data.tar.gz: 69234ea59516677cde345b7e90fd2f253b98819e1d07c8c0286cf3ffc9c4a2bd
 SHA512:
-  metadata.gz: ea803aeac9367ea3427582b3a1b9b1f113c1e60af83e26663c1a5ef50cdde45b5a69a136d373902785c9fc8ca8e98923581735f604fa1c54635aa03f083c64eb
-  data.tar.gz: fb5bfc06c0f1f35b32088dea9247e8878a820c8a95798c4411dbcf8af11e8929e3f0826001ea90afe3ab1a781fcf8c457eb8007a3d348def4a7491cc25778435
+  metadata.gz: 05d907c2ddac65e926e3685030738e21043c685193bd0cf62f36612686a28be9a8028e0eef0cd9edf4548e0617f7d0cc74ee0a2fe5d03df7a2138c19cf38a894
+  data.tar.gz: 4a7d114b6507dae87bbcc760308d4af32eff632aad373d409869f9a04fe114e9c40e9881d0135f2c925389a25bff5ab7812bf58166727fdf7596bf16af404551

data/.envrc

@@ -4,3 +4,4 @@ PATH_add exe
 if [[ -f .env ]]; then
   eval "$(cat .env | sed '/^#.*/d; /^$/d; s/^/export /g')"
 fi
+

data/README.md

@@ -485,6 +485,92 @@ The core has **zero UI logic**, **zero DB logic**, and **zero framework dependen
 | `LLM::SensitiveDataFilter` | Rejects text containing SSN, ITIN, EIN patterns |
 | `Graph::MermaidExporter` | Exports flow as a Mermaid diagram |
 
+## Beyond the DSL: LLM-Driven Tools
+
+The declarative DSL is the primary way to define flows, but it is not the only way to use FlowEngine. The gem's LLM integration layer — adapters, client, and sensitive data filter — can power conversational tools that don't use the DSL at all.
+
+### `bin/tax-estimate` (Experimental)
+
+An interactive CLI tool that estimates tax return complexity and preparation cost entirely through LLM-driven conversation. Instead of defining steps in the DSL, the LLM decides what to ask, generates Ruby code for rich terminal prompts (`TTY::Prompt`), and produces a final YAML estimate when it has enough information.
+
+```bash
+bin/tax-estimate
+```
+
+How it works:
+
+1. A system prompt describes tax complexity factors (filing status, income sources, deductions, special situations)
+2. The LLM returns JSON containing a natural-language question and a `question_eval` field with Ruby code that uses `TTY::Prompt` for multi-select, radio buttons, text input, etc.
+3. The generated code is evaluated to collect the user's answer, which is appended to the chat history
+4. The loop continues until the LLM produces a `final_estimate` — a YAML object with complexity score, cost range, and explanation
+
+This approach trades the safety and predictability of a predefined flow graph for maximum flexibility — the LLM adapts its questions based on prior answers without any step definitions.
+
+```ruby
+# The only FlowEngine dependency is the LLM client
+client = FlowEngine::LLM.auto_client
+response = client.adapter.chat(
+  system_prompt: tax_system_prompt,
+  user_prompt: "Chat history: #{chat_history.to_json}",
+  model: client.model
+)
+```
+
+Here is an example of the final YAML estimate for a simple single-filer return:
+
+```yaml
+---
+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.
+
+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. Rush fees may apply if filing close to the
+    deadline.
+
+estimated_time_to_complete: 1-2 hours
+```
+
+See `examples/` for more sample outputs including complex multi-income scenarios.
+
 ## Ecosystem
 
 | Gem | Purpose |