stellwerk-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 796b4095b7fea502bbfacb3e03aa62ab11fd85234c69e5ee2ebd867e82b1586b
+  data.tar.gz: ef32afa830843674ef9e83175538181c087910be20fd7b9406a927ee192f1bd7
+SHA512:
+  metadata.gz: 882b4adabe5be8af497114eefbd7e0454c145de3b98235de44e77db01e40e588fb56ffc21bc2741ba307cf4b2987a8b5ad6d4d6525ef6c394e1813f7cedb2c70
+  data.tar.gz: 9ed76a0cfc751cb41fcc46c02d2a2fb97e48dcc0ac24ed8570bbe5bb5cbfddf8fdb762d125356db014e5ba963e9f35f442e0b6b7b24f43eac2aaf2f1f0fbb55d

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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] - 2026-01-31
+
+### Added
+
+- Initial release of stellwerk-ruby gem
+- Flow evaluation engine for pre-compiled Stellwerk JSON
+- Support for all core node types:
+  - `start` - Entry point with input validation
+  - `calculate` - Formula evaluation using Dentaku
+  - `condition` - Boolean branching (true/false)
+  - `switch` - Multi-case branching
+  - `merge` - Joins multiple branches
+  - `map` - Array iteration with sub-flow execution
+  - `end` - Output template processing
+- Built-in collection functions:
+  - Aggregation: `SUM`, `COUNT`, `MIN`, `MAX`, `AVERAGE`/`AVG`
+  - Array operations: `FIRST`, `LAST`, `TAKE`, `DISTINCT`, `PROJECT`
+  - Higher-order: `MAP`, `FILTER`, `REDUCE`, `SUMIF`, `COUNTIF`
+- Configuration system with optional logging
+- Result object with success/failure states, outputs, and execution context

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Roadwerk
+
+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,164 @@
+# Stellwerk
+
+A standalone Ruby gem for evaluating pre-compiled Stellwerk flows without any Rails or ActiveRecord dependencies.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stellwerk-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install stellwerk-ruby
+```
+
+## Usage
+
+### Simple Usage
+
+```ruby
+require 'stellwerk'
+
+# Load a compiled flow from a JSON file
+flow = Stellwerk::Flow.load('pricing.compiled.json')
+
+# Execute with input parameters
+result = flow.execute(quantity: 10, price: 25.00)
+
+if result.success?
+  puts result.outputs[:total]
+else
+  puts result.errors
+end
+```
+
+### Direct Evaluator Usage
+
+For more control, you can use the evaluator directly:
+
+```ruby
+require 'stellwerk'
+require 'json'
+
+json = JSON.parse(File.read('flow.json'))
+result = Stellwerk::Evaluator.call(
+  compiled_json: json,
+  params: { x: 10, y: 20 }
+)
+
+puts result.outputs
+puts result.context
+puts result.applied_nodes
+```
+
+### Configuration
+
+```ruby
+require 'logger'
+
+Stellwerk.configure do |config|
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+## Compiled JSON Format
+
+The gem expects compiled flow JSON in this structure:
+
+```json
+{
+  "version": "1.0",
+  "compiled_at": "2026-01-31T12:00:00Z",
+  "entry_node_ids": ["node-1"],
+  "nodes": {
+    "node-1": {
+      "id": "node-1",
+      "name": "Start",
+      "type": "start",
+      "config": { "inputs": [...] }
+    }
+  },
+  "adjacency": {
+    "node-1": [{ "to": "node-2", "branch": null }]
+  },
+  "reverse_adjacency": {
+    "node-2": ["node-1"]
+  },
+  "sub_flows": {
+    "flow-uuid": { ... embedded sub-flow ... }
+  }
+}
+```
+
+## Node Types
+
+The evaluator supports the following node types:
+
+- **start**: Entry point with input validation
+- **calculate**: Formula evaluation using Dentaku
+- **condition**: Boolean branching (true/false)
+- **switch**: Multi-case branching
+- **merge**: Joins multiple branches
+- **map**: Iterates over arrays with sub-flow execution
+- **end**: Output template processing
+
+## Built-in Functions
+
+The gem includes collection functions for use in formulas:
+
+### Aggregation
+- `SUM(array)` or `SUM(a, b, c)`
+- `COUNT(array)`
+- `MIN(array)` / `MAX(array)`
+- `AVERAGE(array)` or `AVG(array)`
+
+### Array Operations
+- `FIRST(array)` / `LAST(array)`
+- `TAKE(array, n)`
+- `DISTINCT(array)`
+- `PROJECT(array, "field")` - Extract field from array of hashes
+
+### Higher-Order Functions
+- `MAP(array, "expression")` - Transform elements
+- `FILTER(array, "predicate")` - Filter elements
+- `REDUCE(array, initial, "expression")` - Reduce to single value
+- `SUMIF(array, "predicate", "projection")` - Conditional sum
+- `COUNTIF(array, "predicate")` - Conditional count
+
+## Result Object
+
+Execution returns a `Stellwerk::Result` object:
+
+```ruby
+result = flow.execute(params)
+
+result.success?       # => true/false
+result.failure?       # => true/false
+result.outputs        # => Hash of output values
+result.errors         # => Array of error messages/hashes
+result.applied_nodes  # => Array of executed nodes
+result.context        # => Full execution context
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/stellwerk/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  # Base error class for all Stellwerk errors
+  class Error < StandardError; end
+
+  # Raised when the compiled JSON is invalid or malformed
+  class InvalidFlowError < Error; end
+
+  # Raised when flow evaluation encounters an error
+  class EvaluationError < Error; end
+
+  # Raised when a required sub-flow is not found
+  class SubFlowNotFoundError < Error; end
+
+  # Raised when a required input is missing
+  class MissingInputError < Error; end
+end