circuit_breaker-wf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86400e938a443a0b3bd0c4b33a5be3da852e0b501a2ea86e19806c554d1f18f8
+  data.tar.gz: 7d9e3ca03f1df4a5c16f80986d60543b82457357e54f088fbfa8dfbb176b774c
+SHA512:
+  metadata.gz: b9bf4f347b32d5079da2a196f3df088f3e7caed14899b63901c3a93a3fd67c4a3cc86951f795a420868855ebf687e0e88302cffdea277258d66dec90b2155df1
+  data.tar.gz: a782c8a67155cc6f468ede3a9638e40e4ecf0b23356fa942fc794f50186cc06d1df8fc33d3f470692b4079bc40b33b8961728d791987260875863873ac5768e3

data/.gitignore

@@ -0,0 +1,4 @@
+.idea
+**.iml
+bin
+.DS_Store

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 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).
+
+## [0.1.0] - 2024-12-11
+
+### Added
+- Initial implementation of Petri Net workflow system
+- Core components:
+  - `Token` class for representing workflow state markers
+  - `Place` class for representing workflow states
+  - `Arc` class for connecting places and transitions
+  - `Transition` class for state change logic
+  - `PetriNet` class for overall workflow management
+- Thread-safe token operations with mutex protection
+- Support for weighted arcs
+- Guard conditions on transitions
+- Token data preservation during transitions
+- JSON serialization for workflow state
+- Example workflow demonstrating approval process
+- Basic project documentation:
+  - README with usage examples and comparisons to Argo Workflows
+  - MIT License
+  - This CHANGELOG
+
+### Technical Details
+- Proper handling of token flow between places and transitions
+- Atomic transition firing with all-or-nothing semantics
+- Step-by-step execution with `step` method
+- Full workflow execution with `run_to_completion`
+- State inspection through `marking` method
+- Thread-safe operations in `Place` and `Transition` classes
+
+## [Unreleased]
+
+### Planned
+- Visualization support for workflow graphs
+- Persistence layer for workflow state
+- Support for timed transitions
+- Advanced synchronization patterns
+- Integration with external systems
+- Web-based workflow designer
+- Performance optimizations for large workflows
+- Additional example workflows
+- Testing framework and test suite
+- CI/CD pipeline setup
+- Documentation website
+- API documentation
+- Contributing guidelines

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in circuit_breaker.gemspec
+gemspec
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", "~> 1.21"
+end

data/Gemfile.lock

@@ -0,0 +1,116 @@
+PATH
+  remote: .
+  specs:
+    circuit_breaker (0.1.0)
+      async
+      concurrent-ruby (~> 1.2)
+      json (~> 2.6)
+      json-schema
+      nats-pure (~> 2.4)
+      nokogiri
+      redcarpet
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.2)
+    async (2.21.1)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.6, >= 1.6.5)
+    bigdecimal (3.1.9)
+    concurrent-ruby (1.3.5)
+    console (1.29.2)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
+    diff-lcs (1.5.1)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.0)
+    io-event (1.7.5)
+    json (2.9.1)
+    json-schema (5.1.1)
+      addressable (~> 2.8)
+      bigdecimal (~> 3.1)
+    language_server-protocol (3.17.0.3)
+    nats-pure (2.4.0)
+      concurrent-ruby (~> 1.0)
+    nokogiri (1.18.1-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.1-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.1-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.1-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.1-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.1-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.1-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.1-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.26.3)
+    parser (3.3.6.0)
+      ast (~> 2.4.1)
+      racc
+    public_suffix (6.0.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    redcarpet (3.6.0)
+    regexp_parser (2.10.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    rubocop (1.70.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.36.2, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.37.0)
+      parser (>= 3.3.1.0)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  circuit_breaker!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.5.11

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Petri Workflows Contributors
+
+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,324 @@
+# Circuit Breaker
+
+Circuit Breaker is a powerful Ruby library that provides a declarative DSL for building AI-powered workflows and assistants. It seamlessly integrates with various LLM providers and offers robust tools for document analysis, workflow management, and autonomous agents.
+
+## Features
+
+### 1. Declarative Workflow DSL
+- State-based workflow engine with intuitive syntax
+- Policy-based transitions with rule chains
+- Unified rules system for validation and transitions
+- Comprehensive history tracking
+- Event handling and state management
+
+### 2. Rules System
+- Unified DSL for defining rules and validations
+- Support for complex rule chains and conditions
+- Built-in helpers for common validations
+- Rule composition with AND/OR logic
+- Clear error reporting and handling
+
+### 3. AI Integration
+- Multiple LLM providers (OpenAI, Ollama)
+- Automatic model detection
+- Tool integration framework
+- Memory management
+- Error handling with retries
+
+### 4. Document Analysis
+- Content quality assessment
+- Sentiment and tone analysis
+- Context detection
+- Improvement suggestions
+- Structure evaluation
+
+### 5. Executors
+- AssistantExecutor for AI-powered tools
+- AgentExecutor for autonomous tasks
+- Custom executor support
+- Chainable tool pipelines
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'circuit_breaker'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install circuit_breaker
+```
+
+## Usage
+
+### Action-Rule Data Flow
+
+Circuit Breaker provides a powerful mechanism for passing data between actions and rules during workflow transitions. Here's how it works:
+
+1. **Actions with Named Results**
+```ruby
+flow :draft >> :pending_review, :submit do
+  actions do
+    # Execute action and store result with key :clarity
+    execute analyzer, :analyze_clarity, :clarity
+  end
+  policy all: [:valid_clarity]
+end
+```
+
+2. **Accessing Results in Rules**
+```ruby
+CircuitBreaker::Rules::DSL.define do
+  rule :valid_clarity do |token|
+    # Retrieve stored result using the same key
+    clarity = context.get_result(:clarity)
+    clarity && clarity[:score] >= 70
+  end
+end
+```
+
+3. **Data Flow Process**
+   - Actions are executed first during a transition
+   - Results are stored in an action context using the specified key
+   - Rules can access these results through the same key
+   - This enables rules to validate based on action outputs
+
+This pattern allows for:
+- Clean separation between action execution and rule validation
+- Reusable actions with different validation rules
+- Complex rule chains based on multiple action results
+- Clear data flow tracking during transitions
+
+### Creating a Workflow
+
+```ruby
+# Define rules
+rules = CircuitBreaker::Rules::DSL.define do
+  rule :valid_reviewer do |token|
+    token.reviewer_id.present?
+  end
+
+  rule :valid_review do |token|
+    token.reviewer_comments.present?
+  end
+end
+
+# Define workflow
+workflow = CircuitBreaker::WorkflowDSL.define(rules: rules) do
+  # Define states
+  states :draft, :pending_review, :reviewed, :approved, :rejected
+
+  # Define transitions with rules
+  flow(:draft >> :pending_review)
+    .transition(:submit)
+    .policy(rules: { all: [:valid_reviewer] })
+
+  flow(:pending_review >> :reviewed)
+    .transition(:review)
+    .policy(
+      rules: {
+        all: [:valid_review],
+        any: [:is_high_priority, :is_urgent]
+      }
+    )
+end
+
+# Create and add token
+token = CircuitBreaker::Token.new
+workflow.add_token(token)
+
+# Fire transitions
+workflow.fire_transition(:submit, token)
+```
+
+### History Tracking
+
+The workflow automatically tracks all transitions:
+
+```ruby
+token.history.each do |event|
+  puts "#{event[:timestamp]}: #{event[:transition]} from #{event[:from]} to #{event[:to]}"
+end
+```
+
+## Architecture
+
+Circuit Breaker uses a hybrid architecture combining:
+
+1. **Workflow Engine**: Based on Petri nets for formal verification
+2. **Rules Engine**: Unified system for validations and transitions
+3. **AI Integration**: Pluggable LLM providers for analysis
+4. **Event System**: Comprehensive tracking and auditing
+
+While basic Petri nets are not Turing complete, our implementation is closer to Colored Petri Nets (CPNs) or High-level Petri Nets. The system balances theoretical power with practical utility, providing:
+- Sufficient expressiveness for real-world business processes
+- Analyzability for critical property verification
+- Maintainable and understandable structure through the workflow DSL
+
+## Components
+
+### 1. Workflow Engine
+
+The workflow engine provides:
+- State management
+- Transition validation
+- Rule enforcement
+- Event tracking
+- History management
+
+Example:
+```ruby
+# Define rules
+rule :has_reviewer,
+     desc: "Document must have a reviewer assigned",
+     &requires(:reviewer_id)
+
+# Define validations
+validator :title,
+         desc: "Document title is required",
+         &must_be_present(:title)
+
+# Create workflow instance
+workflow = DocumentWorkflow.new(document)
+workflow.submit  # Transition to pending_review
+```
+
+### 2. AI Executors
+
+Two main executor types:
+
+1. AssistantExecutor
+   - Tool-based execution
+   - Context management
+   - Memory persistence
+   - Error handling
+
+2. AgentExecutor
+   - Autonomous task execution
+   - Tool discovery
+   - Planning capabilities
+   - Progress tracking
+
+### 3. Tool Framework
+
+Tools can be:
+- Basic tools with direct execution
+- Chainable tools for complex pipelines
+- Stateful tools with context
+- Fallback-enabled tools
+
+Example chainable tool:
+```ruby
+class ChainableTool < CircuitBreaker::Executors::LLM::ChainableTool
+  def initialize
+    super(
+      name: 'chainable_tool',
+      description: 'Part of processing pipeline',
+      input_schema: { type: 'string' },
+      output_schema: { type: 'object' }
+    )
+  end
+
+  def execute(input, context)
+    result = process(input)
+    next_tool = context.available_tools.find { |t| t.can_handle?(result) }
+    context.chain(next_tool) if next_tool
+  end
+end
+```
+
+## Examples
+
+See the `examples` directory for complete examples:
+
+1. Document Workflow
+   - Complete document management system
+   - AI-powered analysis
+   - Review process automation
+   - State tracking
+
+2. Research Assistant
+   - Autonomous research agent
+   - Source gathering
+   - Summary generation
+   - Citation management
+
+## Configuration
+
+### 1. LLM Providers
+
+```ruby
+# Configure Ollama
+CircuitBreaker.configure do |config|
+  config.ollama_base_url = 'http://localhost:11434'
+  config.default_model = 'qwen2.5-coder'
+end
+
+# Configure OpenAI
+CircuitBreaker.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.default_model = 'gpt-4'
+end
+```
+
+### 2. Memory Settings
+
+```ruby
+CircuitBreaker.configure do |config|
+  config.max_memory_tokens = 4000
+  config.memory_window_size = 10
+end
+```
+
+### 3. Tool Settings
+
+```ruby
+CircuitBreaker.configure do |config|
+  config.default_tools = [
+    ContentAnalysisTool,
+    SentimentAnalysisTool,
+    ImprovementTool
+  ]
+  config.tool_timeout = 30  # seconds
+end
+```
+
+## Best Practices
+
+1. Workflow Design
+   - Keep states and transitions clear
+   - Use descriptive rule names
+   - Implement proper validation
+   - Track state changes
+
+2. AI Integration
+   - Choose appropriate models
+   - Handle errors gracefully
+   - Implement retries
+   - Monitor performance
+
+3. Tool Development
+   - Keep tools focused
+   - Provide clear descriptions
+   - Include fallback behavior
+   - Handle errors appropriately
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Add tests for new features
+4. Submit a pull request
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

data/examples/document/README.md

@@ -0,0 +1,150 @@
+# Document Workflow Examples
+
+This directory contains examples demonstrating how to use the Circuit Breaker library to implement a document workflow system with AI-powered analysis. The examples showcase a declarative DSL for defining workflows, rules, validations, and AI-powered document analysis.
+
+## Overview
+
+The document workflow system implements a document review and approval process with the following states:
+- `draft`: Initial state for new documents
+- `pending_review`: Document submitted for review
+- `reviewed`: Review completed with comments
+- `approved`: Document approved by manager
+- `rejected`: Document rejected with reasons
+
+## Features
+
+### 1. Unified Rules System
+- Declarative rule definitions using DSL
+- Complex rule chains with AND/OR logic
+- Built-in validation helpers
+- Clear error reporting
+- Rule reusability across transitions
+
+### 2. Workflow Management
+- Intuitive state transition syntax (`from >> to`)
+- Policy-based transitions with rule chains
+- Comprehensive history tracking
+- Event handling and state management
+- Automatic validation during transitions
+
+### 3. Document Rules
+- Document validation rules:
+  - `valid_reviewer`: Ensures reviewer is assigned
+  - `valid_review`: Validates review comments
+  - `valid_approver`: Checks approver assignment
+  - `is_admin_approver`: Verifies approver permissions
+  - `valid_word_count`: Checks document length
+  - `valid_external_url`: Validates external references
+
+### 4. AI-Powered Document Analysis
+- Content quality and structure assessment
+- Sentiment and tone analysis
+- Automatic context detection
+- Improvement suggestions
+- Word count validation
+
+## Example Usage
+
+### 1. Define Document Rules
+
+```ruby
+rules = DocumentRules.define do
+  rule :valid_reviewer do |token|
+    token.reviewer_id.present?
+  end
+
+  rule :valid_review do |token|
+    token.reviewer_comments.present?
+  end
+
+  rule :is_admin_approver do |token|
+    token.approver_id&.start_with?('admin_')
+  end
+end
+```
+
+### 2. Create Workflow
+
+```ruby
+workflow = CircuitBreaker::WorkflowDSL.define(rules: rules) do
+  states :draft, :pending_review, :reviewed, :approved, :rejected
+
+  flow(:draft >> :pending_review)
+    .transition(:submit)
+    .policy(rules: { all: [:valid_reviewer] })
+
+  flow(:pending_review >> :reviewed)
+    .transition(:review)
+    .policy(
+      rules: {
+        all: [:valid_review],
+        any: [:is_high_priority, :is_urgent]
+      }
+    )
+
+  flow(:reviewed >> :approved)
+    .transition(:approve)
+    .policy(
+      rules: {
+        all: [:valid_approver, :valid_review, :is_admin_approver],
+        any: [:valid_external_url, :valid_word_count]
+      }
+    )
+end
+```
+
+### 3. Process Document
+
+```ruby
+# Create document
+token = Examples::DocumentToken.new(
+  title: "Project Proposal",
+  content: "Detailed project proposal...",
+  priority: "high",
+  author_id: "charlie789"
+)
+
+# Add to workflow
+workflow.add_token(token)
+
+# Submit document
+token.reviewer_id = "bob456"
+workflow.fire_transition(:submit, token)
+
+# Review document
+token.reviewer_comments = "Detailed review comments..."
+workflow.fire_transition(:review, token)
+
+# Approve document
+token.approver_id = "admin_eve789"
+workflow.fire_transition(:approve, token)
+
+# View history
+token.history.each do |event|
+  puts "#{event[:timestamp]}: #{event[:transition]} from #{event[:from]} to #{event[:to]}"
+end
+```
+
+## Files
+
+- `document_token.rb`: Token class for documents
+- `document_rules.rb`: Rule definitions for document workflow
+- `document_workflow.rb`: Main workflow implementation
+- `document_assistant.rb`: AI-powered document analysis
+
+## Requirements
+
+1. Ruby 2.7 or higher
+2. Ollama installed and running locally (for AI-powered document analysis)
+
+## Running the Example
+
+```bash
+ruby document_workflow.rb
+```
+
+This will execute the example workflow, showing:
+1. Workflow definition and states
+2. Document transitions through states
+3. Rule validations at each step
+4. Complete transition history