flowengine 0.3.1 → 0.4.0

data/docs/PROJECT_STRUCTURE.md

@@ -0,0 +1,64 @@
+# Project Structure
+
+```text
+lib/flowengine/
+  flowengine.rb              # Module entry: define() and load_dsl()
+  version.rb                 # VERSION = "0.3.1"
+  errors.rb                  # Error hierarchy (8 classes)
+  clarification_result.rb    # Data.define for AI intake round results
+  introduction.rb            # Data.define(:label, :placeholder, :maxlength)
+  definition.rb              # Immutable flow graph container
+  node.rb                    # Single flow step (question, type, transitions, max_clarifications)
+  transition.rb              # Directed edge with optional rule condition
+  evaluator.rb               # Rule evaluation against answers
+  engine.rb                  # Runtime session (answers, history, navigation, AI intake state)
+  engine/
+    state_serializer.rb      # Symbolizes string-keyed state from JSON round-trips
+  dsl/
+    flow_builder.rb          # FlowEngine.define {} context (start, introduction, step)
+    step_builder.rb          # step {} block builder (includes max_clarifications)
+    rule_helpers.rb          # contains(), equals(), all(), any(), etc.
+  rules/
+    base.rb                  # Abstract rule (evaluate + to_s)
+    contains.rb              # Array.include? semantics
+    equals.rb                # Simple equality
+    greater_than.rb          # Numeric > comparison (coerces to_i)
+    less_than.rb             # Numeric < comparison (coerces to_i)
+    not_empty.rb             # !nil && !empty?
+    all.rb                   # Composite AND
+    any.rb                   # Composite OR
+  validation/
+    adapter.rb               # Abstract validator interface
+    null_adapter.rb          # No-op default validator
+  llm/
+    adapter.rb               # Abstract LLM adapter interface
+    adapters.rb              # Requires all concrete adapters
+    auto_client.rb           # FlowEngine::LLM.auto_client factory
+    provider.rb              # Provider/model registry from models.yml
+    client.rb                # High-level LLM client (prompt building + response parsing)
+    system_prompt_builder.rb # Builds system prompt for introduction pre-fill
+    intake_prompt_builder.rb # Builds system prompt for AI intake steps
+    sensitive_data_filter.rb # Rejects SSN, ITIN, EIN patterns
+  graph/
+    mermaid_exporter.rb      # Exports Definition to Mermaid diagram
+resources/
+  models.yml                 # Vendor/model registry (Anthropic, OpenAI, Gemini)
+  prompts/
+    generic-dsl-intake.j2    # Static system prompt template for LLM parsing
+spec/
+  flowengine_spec.rb         # Top-level define/load_dsl tests
+  flowengine/                # Mirrors lib/ structure
+    engine_spec.rb           # Core engine tests
+    engine_ai_intake_spec.rb # AI intake step tests
+    engine_introduction_spec.rb # Introduction pre-fill tests
+    engine_state_spec.rb     # State persistence tests
+    clarification_result_spec.rb
+    llm/                     # LLM adapter, client, filter, prompt builder specs
+  integration/
+    introduction_flow_spec.rb # Introduction + LLM pre-fill integration
+    multi_ai_intake_spec.rb  # Multi-AI intake integration test
+    tax_intake_flow_spec.rb  # Real-world tax intake example
+    complex_flow_spec.rb     # Complex branching tests
+  fixtures/
+    complex_tax_intake.rb    # 17-step tax intake flow definition
+```

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.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 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,18 @@ 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
 - exe/flowengine
 - justfile
+- lefthook.yml
 - lib/flowengine.rb
 - lib/flowengine/clarification_result.rb
 - lib/flowengine/definition.rb
@@ -144,6 +176,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