flow_nodes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d43ed2ccf1e7333f3e4f7f0f61b12c35adeeb020bfc4af99c52e8f3b37a93e0
+  data.tar.gz: 69d609ccf71175c6a67eb92c70757bf6c122c76b2738eb25eeedb5289e3be6ba
+SHA512:
+  metadata.gz: 1c5df694422c2337a346c54595ad1694247f6756c59c7d2352dd7e44c68f01039b214d626100b83f7a372184b11380abd2fe329830ef8528727921c169b583c2
+  data.tar.gz: 5f8cd50d2ea00c2bbcf735851c3aa4cfc5a79b71afa1870cec1a06de7d9ebefb726e2e8f3769d9b235c3a4750710231e1fcd0760ac2a0337e0cf64ff62bbe38a

data/.qlty.yml

@@ -0,0 +1,40 @@
+# Qlty configuration for FlowNodes
+version: 1
+
+# Coverage configuration
+coverage:
+  exclude_paths:
+    - "spec/**/*"
+    - "examples/**/*"
+    - "vendor/**/*"
+    - "tmp/**/*"
+    - "bin/**/*"
+  
+  # Minimum coverage thresholds
+  thresholds:
+    total: 90
+    changed: 80
+
+# Code quality tools
+tools:
+  rubocop:
+    enabled: true
+    config: .rubocop.yml
+  
+  reek:
+    enabled: false  # Disable reek for now
+  
+  bundler_audit:
+    enabled: true
+
+# Issue tracking
+issues:
+  exclude_paths:
+    - "spec/**/*"
+    - "examples/**/*"
+    - "vendor/**/*"
+
+# Formatting
+formatting:
+  exclude_paths:
+    - "examples/**/*"  # Allow examples to be more relaxed

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,53 @@
+# RuboCop configuration for FlowNodes
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+    - 'examples/**/*'
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+# Style
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+# Metrics
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Max: 30
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+    - '*.gemspec'
+
+# Naming
+Naming/MethodParameterName:
+  MinNameLength: 1

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of FlowNodes gem
+- Core node and flow architecture
+- BaseNode class with parameter management and connections
+- Node class with retry logic and lifecycle hooks
+- Flow class for orchestrating node execution
+- BatchNode for sequential batch processing
+- AsyncNode for asynchronous execution
+- AsyncBatchNode for async sequential batch processing
+- AsyncParallelBatchNode for parallel batch processing
+- AsyncFlow for orchestrating async and sync nodes
+- AsyncBatchFlow for async batch processing
+- AsyncParallelBatchFlow for parallel batch processing
+- ConditionalTransition for conditional flow routing
+- Comprehensive test suite with 181 tests
+- Thread-safe parameter isolation with deep copying
+- Retry mechanisms with customizable fallbacks
+- Lifecycle hooks (prep, exec, post)
+- Examples directory with practical use cases
+- GitHub Actions CI/CD workflow
+- RuboCop configuration for code quality
+- SimpleCov for code coverage tracking
+- Qlty integration for code quality and coverage monitoring
+- YARD documentation support
+- Comprehensive README with usage examples
+
+### Changed
+- Refactored monolithic structure to use individual class files
+- Fixed parameter passing issues in async execution
+- Improved array handling in batch processing
+- Enhanced error handling in async flows
+- Optimized performance for I/O-bound tasks
+
+### Fixed
+- Parameter flow through prep() → _run() → _orch() → _exec() → exec()
+- Array handling to prevent hash-to-array conversion issues
+- Post hook parameter passing in async operations
+- Conditional flow routing in async contexts
+- Thread safety issues in parallel processing
+- Retry logic consistency across all node types
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+- Initial release with core FlowNodes framework
+- Ruby port of PocketFlow's minimalist LLM architecture
+- Production-ready architecture with clean separation of concerns
+- Support for Ruby 3.1+ with proper dependency management
+- MIT license for open source usage
+- Full compatibility with PocketFlow's design patterns and philosophy

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 RJ Robinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,315 @@
+# FlowNodes
+
+[![Gem Version](https://badge.fury.io/rb/flow_nodes.svg)](https://badge.fury.io/rb/flow_nodes)
+[![CI](https://github.com/rjrobinson/flow_nodes/workflows/CI/badge.svg)](https://github.com/rjrobinson/flow_nodes/actions)
+[![Qlty](https://img.shields.io/badge/code_quality-qlty-brightgreen.svg)](https://qlty.sh/)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A Ruby port of the minimalist LLM framework, [PocketFlow](https://github.com/The-Pocket/PocketFlow).**
+
+FlowNodes is a Ruby gem that brings the lightweight, expressive power of [PocketFlow](https://github.com/The-Pocket/PocketFlow) to the Ruby ecosystem. It provides a minimal, graph-based core for building powerful LLM applications like Agents, Workflows, and RAG, without the bloat of larger frameworks.
+
+## Design Philosophy
+
+FlowNodes is inspired by and based on [PocketFlow](https://github.com/The-Pocket/PocketFlow), a Python framework created by [The Pocket](https://github.com/The-Pocket). We've adapted PocketFlow's elegant, minimalist approach to LLM application development for the Ruby ecosystem.
+
+**Core principles:**
+- **Minimalist Design**: Core functionality in under 500 lines of code
+- **Graph-based Architecture**: Connect nodes to create complex workflows
+- **LLM-First**: Built specifically for Large Language Model applications
+- **Extensible**: Easy to extend with custom nodes and flows
+
+FlowNodes maintains the same philosophy and API patterns as PocketFlow while providing a native Ruby experience. This ensures Ruby developers can leverage the proven design patterns that make PocketFlow so effective.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  gem 'flow_nodes'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install flow_nodes
+```
+
+## Features
+
+- **Minimal & Lightweight**: Core framework in under 500 lines of code
+- **Graph-based**: Build complex workflows with simple node connections
+- **Async Support**: Built-in async and parallel processing capabilities
+- **Batch Processing**: Sequential and parallel batch operations
+- **Retry Logic**: Built-in retry mechanisms with customizable fallbacks
+- **Thread Safety**: Proper isolation and deep copying for concurrent execution
+- **Extensible**: Easy to extend with custom nodes and flows
+- **Production Ready**: Comprehensive test coverage and clean architecture
+
+## Quick Start
+
+### Basic Node and Flow
+
+```ruby
+require 'flow_nodes'
+
+class GreetingNode < FlowNodes::Node
+  def exec(params)
+    puts "Hello, #{params[:name]}!"
+    "greeted"
+  end
+end
+
+class FarewellNode < FlowNodes::Node
+  def exec(params)
+    puts "Goodbye, #{params[:name]}!"
+    nil # End the flow
+  end
+end
+
+# Create nodes
+greeting = GreetingNode.new
+farewell = FarewellNode.new
+
+# Connect nodes: greeting -> farewell
+greeting - :greeted >> farewell
+
+# Create and run flow
+flow = FlowNodes::Flow.new(start: greeting)
+flow.set_params(name: "World")
+flow.run(nil)
+```
+
+### Conditional Flows
+
+```ruby
+class ValidationNode < FlowNodes::Node
+  def exec(params)
+    params[:email]&.include?("@") ? "valid" : "invalid"
+  end
+end
+
+class ProcessNode < FlowNodes::Node
+  def exec(params)
+    puts "Processing #{params[:email]}"
+    nil
+  end
+end
+
+class ErrorNode < FlowNodes::Node
+  def exec(params)
+    puts "Error: Invalid email #{params[:email]}"
+    nil
+  end
+end
+
+validator = ValidationNode.new
+processor = ProcessNode.new
+error_handler = ErrorNode.new
+
+# Branch based on validation result
+validator - :valid >> processor
+validator - :invalid >> error_handler
+
+flow = FlowNodes::Flow.new(start: validator)
+flow.set_params(email: "user@example.com")
+flow.run(nil)
+```
+
+### Batch Processing
+
+```ruby
+class DataProcessor < FlowNodes::BatchNode
+  def exec(item)
+    puts "Processing: #{item}"
+    item.upcase
+  end
+end
+
+processor = DataProcessor.new
+processor.set_params(["hello", "world", "ruby"])
+results = processor.run(nil)
+# => ["HELLO", "WORLD", "RUBY"]
+```
+
+### Async and Parallel Processing
+
+```ruby
+class AsyncProcessor < FlowNodes::AsyncParallelBatchNode
+  def exec_async(item)
+    puts "Processing #{item} on thread #{Thread.current.object_id}"
+    sleep(0.1) # Simulate I/O
+    item.upcase
+  end
+end
+
+processor = AsyncProcessor.new
+processor.set_params(["hello", "world", "ruby"])
+results = processor.run_async(nil)
+# Processes all items in parallel
+```
+
+### Lifecycle Hooks
+
+```ruby
+class LoggingNode < FlowNodes::Node
+  def prep(state)
+    puts "Preparing to process"
+    { prepared_at: Time.now }
+  end
+
+  def exec(params)
+    puts "Processing: #{params}"
+    "success"
+  end
+
+  def post(state, params, result)
+    puts "Completed with result: #{result}"
+  end
+end
+```
+
+### Error Handling and Retries
+
+```ruby
+class RetryNode < FlowNodes::Node
+  def initialize
+    super(max_retries: 3, wait: 1)
+  end
+
+  def exec(params)
+    # Simulate unreliable operation
+    raise "Network error" if rand < 0.7
+    "success"
+  end
+
+  def exec_fallback(params, exception)
+    puts "All retries failed: #{exception.message}"
+    "failed"
+  end
+end
+```
+
+## Architecture
+
+FlowNodes is built around several core classes:
+
+- **`BaseNode`**: Foundation class with parameter management and connections
+- **`Node`**: Adds retry logic and lifecycle hooks
+- **`Flow`**: Orchestrates node execution and state management
+- **`BatchNode`**: Processes arrays of items sequentially
+- **`AsyncNode`**: Enables asynchronous execution
+- **`AsyncBatchNode`**: Async sequential batch processing
+- **`AsyncParallelBatchNode`**: Async parallel batch processing
+- **`AsyncFlow`**: Orchestrates async and sync nodes together
+
+## Examples
+
+See the [`examples/`](examples/) directory for complete examples:
+
+- [`examples/chatbot.rb`](examples/chatbot.rb) - Interactive chatbot with self-loops
+- [`examples/workflow.rb`](examples/workflow.rb) - Data validation and processing workflow
+- [`examples/batch_processing.rb`](examples/batch_processing.rb) - Sequential and parallel batch operations
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+# Run RuboCop for style checking
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+
+# Generate documentation
+bundle exec yard doc
+```
+
+### CI/CD Setup
+
+The project uses GitHub Actions for CI/CD with the following secrets required:
+
+- `QLTY_COVERAGE_TOKEN`: Token for Qlty code coverage reporting
+- `RUBYGEMS_AUTH_TOKEN`: Token for publishing to RubyGems (optional)
+
+### Running Examples
+
+```bash
+# Run the chatbot example
+ruby examples/chatbot.rb
+
+# Run the workflow example
+ruby examples/workflow.rb
+
+# Run the batch processing example
+ruby examples/batch_processing.rb
+```
+
+## API Reference
+
+For detailed API documentation, visit the [YARD documentation](https://rubydoc.info/gems/flow_nodes) or generate it locally:
+
+```bash
+bundle exec yard doc
+open doc/index.html
+```
+
+## Performance Considerations
+
+- **Async Operations**: Use Ruby threads, subject to the GVL. Best for I/O-bound tasks.
+- **Parallel Processing**: `AsyncParallelBatchNode` provides concurrency for I/O operations.
+- **Memory**: Deep copying ensures thread safety but uses more memory.
+- **Batch Size**: Consider batch sizes for memory usage vs. processing efficiency.
+
+## Thread Safety
+
+FlowNodes is designed to be thread-safe:
+
+- Parameters are deep-copied using `Marshal` to prevent state bleed
+- Each flow execution operates on isolated node instances
+- Shared state objects should be managed carefully in multi-threaded environments
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass (`bundle exec rspec`)
+6. Run RuboCop (`bundle exec rubocop`)
+7. Commit your changes (`git commit -am 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
+
+## Acknowledgments
+
+This project is a Ruby port of the excellent [PocketFlow](https://github.com/The-Pocket/PocketFlow) Python framework created by [The Pocket](https://github.com/The-Pocket). 
+
+**Special thanks to:**
+- The original PocketFlow team for pioneering the minimalist LLM framework approach
+- The Python community for inspiring clean, expressive API design
+- The Ruby community for providing excellent tools and libraries that made this port possible
+
+FlowNodes would not exist without the groundbreaking work of the PocketFlow team. We encourage users to also check out the [original Python PocketFlow](https://github.com/The-Pocket/PocketFlow) and its excellent [documentation](https://the-pocket.github.io/PocketFlow/).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]