zen-engine-ruby 0.0.1-arm64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63f1b2424a26f1de1db9147cbf2dd4bb94215952048ffae4fe3de9712c3e233e
+  data.tar.gz: 5e5821ff114726654d26bf74f7dcc313683846881ee3862385e0948f62781e8c
+SHA512:
+  metadata.gz: d644560322306752e346cf9931a74d978d3eb5721b11ff124df89ee942020e8772bc916065f3171aa82348b6c467a29447e9d136935af2669790384070a3c381
+  data.tar.gz: 18f1d5d884b4cae5d4d55c0e18f6ce230f4fa1f300458bf531611c3cade4c7fd3d31bb59eaec3c09fd879129c5678da0a3f65a121d8e9f0c2524cdfc19fab1e5

data/LICENSE

@@ -0,0 +1,31 @@
+ZEN-Ruby License (MIT)
+
+Copyright 2024 FutureProof Retail
+
+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.
+
+GoRules ZEN Engine License Reproduced Below:
+
+Copyright 2024 GoRules.io
+
+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,329 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+# ZEN Rules Engine for Ruby (ALPHA)
+
+Ruby Bindings for the [GoRules Zen Business Rules Engine](https://github.com/gorules/zen).
+
+ZEN Engine is a cross-platform, Open-Source Business Rules Engine (BRE). It is written in Rust and provides native 
+bindings for **NodeJS**, **Python**, **Ruby**, and **Go**. ZEN Engine allows to load and execute JSON Decision Model (JDM) from JSON files.
+
+<img width="800" alt="Open-Source Rules Engine" src="https://gorules.io/images/jdm-editor.gif">
+
+An open-source React editor is available on our [JDM Editor](https://github.com/gorules/jdm-editor) repo.
+
+## Installation
+
+```bash
+# TODO: deploy to rubygems
+# gem install zen-engine-ruby
+```
+
+## Usage
+
+ZEN Engine is built as embeddable BRE for your **Ruby**, **Rust**, **NodeJS**, **Python** or **Go** applications.
+It parses JDM from JSON content. It is up to you to obtain the JSON content, e.g. from file system, database or service call.
+
+### Load and Execute Rules
+
+TODO: write this section. In the meantime, take a look at [test.rb](./test.rb) for how to use this API.
+
+### Supported Platforms
+
+List of platforms where Zen Engine is natively available:
+
+* **Ruby** - [GitHub](https://github.com/FutureProofRetail/zen-engine-ruby/README.md)
+* **NodeJS** - [GitHub](https://github.com/gorules/zen/blob/master/bindings/nodejs/README.md) | [Documentation](https://gorules.io/docs/developers/bre/engines/nodejs) | [npmjs](https://www.npmjs.com/package/@gorules/zen-engine)
+* **Python** - [GitHub](https://github.com/gorules/zen/blob/master/bindings/python/README.md) | [Documentation](https://gorules.io/docs/developers/bre/engines/python) | [pypi](https://pypi.org/project/zen-engine/)
+* **Go** - [GitHub](https://github.com/gorules/zen-go) | [Documentation](https://gorules.io/docs/developers/bre/engines/go)
+* **Rust (Core)** - [GitHub](https://github.com/gorules/zen) | [Documentation](https://gorules.io/docs/developers/bre/engines/rust) | [crates.io](https://crates.io/crates/zen-engine)
+
+For a complete **Business Rules Management Systems (BRMS)** solution:
+
+* [Self-hosted BRMS](https://gorules.io)
+* [GoRules Cloud BRMS](https://gorules.io/signin/verify-email)
+
+## JSON Decision Model (JDM)
+
+GoRules JDM (JSON Decision Model) is a modeling framework designed to streamline the representation and implementation
+of decision models.
+
+#### Understanding GoRules JDM
+
+At its core, GoRules JDM revolves around the concept of decision models as interconnected graphs stored in JSON format.
+These graphs capture the intricate relationships between various decision points, conditions, and outcomes in a GoRules
+Zen-Engine.
+
+Graphs are made by linking nodes with edges, which act like pathways for moving information from one node to another,
+usually from the left to the right.
+
+The Input node serves as an entry for all data relevant to the context, while the Output nodes produce the result of
+decision-making process. The progression of data follows a path from the Input Node to the Output Node, traversing all
+interconnected nodes in between. As the data flows through this network, it undergoes evaluation at each node, and
+connections determine where the data is passed along the graph.
+
+To see JDM Graph in action you can use [Free Online Editor](https://editor.gorules.io) with built in Simulator.
+
+There are 5 main node types in addition to a graph Input Node (Request) and Output Node (Response):
+
+* Decision Table Node
+* Switch Node
+* Function Node
+* Expression Node
+* Decision Node
+
+### Decision Table Node
+
+#### Overview
+
+Tables provide a structured representation of decision-making processes, allowing developers and business users to
+express complex rules in a clear and concise manner.
+
+<img width="960" alt="Decision Table" src="https://gorules.io/images/decision-table.png">
+
+#### Structure
+
+At the core of the Decision Table is its schema, defining the structure with inputs and outputs. Inputs encompass
+business-friendly expressions using the ZEN Expression Language, accommodating a range of conditions such as equality,
+numeric comparisons, boolean values, date time functions, array functions and more. The schema's outputs dictate the
+form of results generated by the Decision Table.
+Inputs and outputs are expressed through a user-friendly interface, often resembling a spreadsheet. This facilitates
+easy modification and addition of rules, enabling business users to contribute to decision logic without delving into
+intricate code.
+
+#### Evaluation Process
+
+Decision Tables are evaluated row by row, from top to bottom, adhering to a specified hit policy.
+Single row is evaluated via Inputs columns, from left to right. Each input column represents `AND` operator. If cell is
+empty that column is evaluated **truthfully**, independently of the value.
+
+If a single cell within a row fails (due to error, or otherwise), the row is skipped.
+
+**HitPolicy**
+
+The hit policy determines the outcome calculation based on matching rules.
+
+The result of the evaluation is:
+
+* **an object** if the hit policy of the decision table is `first` and a rule matched. The structure is defined by the
+  output fields. Qualified field names with a dot (.) inside lead to nested objects.
+* **`null`/`undefined`** if no rule matched in `first` hit policy
+* **an array of objects** if the hit policy of the decision table is `collect` (one array item for each matching rule)
+  or empty array if no rules match
+
+#### Inputs
+
+In the assessment of rules or rows, input columns embody the `AND` operator. The values typically consist of (qualified)
+names, such as `customer.country` or `customer.age`.
+
+There are two types of evaluation of inputs, `Unary` and `Expression`.
+
+**Unary Evaluation**
+
+Unary evaluation is usually used when we would like to compare single fields from incoming context separately, for
+example `customer.country` and `cart.total` . It is activated when a column has `field` defined in its schema.
+
+***Example***
+
+For the input:
+
+```json
+{
+  "customer": {
+    "country": "US"
+  },
+  "cart": {
+    "total": 1500
+  }
+}
+```
+
+<img width="960" alt="Decision Table Unary Test" src="https://gorules.io/images/decision-table.png">
+
+This evaluation translates to
+
+```
+IF customer.country == 'US' AND cart.total > 1000 THEN {"fees": {"percent": 2}}
+ELSE IF customer.country == 'US' THEN {"fees": {"flat": 30}}
+ELSE IF customer.country == 'CA' OR customer.country == 'MX' THEN {"fees": {"flat": 50}}
+ELSE {"fees": {"flat": 150}}
+```
+
+List shows basic example of the unary tests in the Input Fields:
+
+| Input entry | Input Expression                               |
+|-------------|------------------------------------------------|
+| "A"         | the field equals "A"                           |
+| "A", "B"    | the field is either "A" or "B"                 |
+| 36          | the numeric value equals 36                    |
+| < 36        | a value less than 36                           |
+| > 36        | a value greater than 36                        |
+| [20..39]    | a value between 20 and 39 (inclusive)          |
+| 20,39       | a value either 20 or 39                        |
+| <20, >39    | a value either less than 20 or greater than 39 |
+| true        | the boolean value true                         |
+| false       | the boolean value false                        |
+|             | any value, even null/undefined                 |
+| null        | the value null or undefined                    |
+
+Note: For the full list please
+visit [ZEN Expression Language](https://gorules.io/docs/rules-engine/expression-language/).
+
+**Expression Evaluation**
+
+Expression evaluation is used when we would like to create more complex evaluation logic inside single cell. It allows
+us to compare multiple fields from the incoming context inside same cell.
+
+It can be used by providing an empty `Selector (field)` inside column configuration.
+
+***Example***
+
+For the input:
+
+```json
+{
+  "transaction": {
+    "country": "US",
+    "createdAt": "2023-11-20T19:00:25Z",
+    "amount": 10000
+  }
+}
+```
+
+<img width="960" alt="Decision Table Expression" src="https://gorules.io/images/decision-table-expression.png">
+
+```
+IF time(transaction.createdAt) > time("17:00:00") AND transaction.amount > 1000 THEN {"status": "reject"}
+ELSE {"status": "approve"}
+```
+
+Note: For the full list please
+visit [ZEN Expression Language](https://gorules.io/docs/rules-engine/expression-language/).
+
+**Outputs**
+
+Output columns serve as the blueprint for the data that the decision table will generate when the conditions are met
+during evaluation.
+
+When a row in the decision table satisfies its specified conditions, the output columns determine the nature and
+structure of the information that will be returned. Each output column represents a distinct field, and the collective
+set of these fields forms the output or result associated with the validated row. This mechanism allows decision tables
+to precisely define and control the data output.
+
+***Example***
+
+<img width="860" alt="Decision Table Output" src="https://gorules.io/images/decision-table-output.png">
+
+And the result would be:
+
+```json
+{
+  "flatProperty": "A",
+  "output": {
+    "nested": {
+      "property": "B"
+    },
+    "property": 36
+  }
+}
+```
+
+### Switch Node (NEW)
+
+The Switch node in GoRules JDM introduces a dynamic branching mechanism to decision models, enabling the graph to
+diverge based on conditions.
+
+Conditions are written in a Zen Expression Language.
+
+By incorporating the Switch node, decision models become more flexible and context-aware. This capability is
+particularly valuable in scenarios where diverse decision logic is required based on varying inputs. The Switch node
+efficiently manages branching within the graph, enhancing the overall complexity and realism of decision models in
+GoRules JDM, making it a pivotal component for crafting intelligent and adaptive systems.
+
+The Switch node preserves the incoming data without modification; it forwards the entire context to the output branch(
+es).
+
+<img width="960" alt="Switch / Branching" src="https://gorules.io/images/decision-graph.png">
+
+#### HitPolicy
+
+There are two HitPolicy options for the switch node, `first` and `collect`.
+
+In the context of a first hit policy, the graph branches to the initial matching condition, analogous to the behavior
+observed in a table. Conversely, under a collect hit policy, the graph extends to all branches where conditions hold
+true, allowing branching to multiple paths.
+
+Note: If there are multiple edges from the same condition, there is no guaranteed order of execution.
+
+*Available from:*
+
+* Python 0.16.0
+* NodeJS 0.13.0
+* Rust 0.16.0
+* Go 0.1.0
+
+### Functions Node
+
+Function nodes are JavaScript snippets that allow for quick and easy parsing, re-mapping or otherwise modifying the data
+using JavaScript. Inputs of the node are provided as function's arguments. Functions are executed on top of QuickJS
+Engine that is bundled into the ZEN Engine.
+
+Function timeout is set to a 50ms.
+
+```js
+const handler = (input, {dayjs, Big}) => {
+    return {
+        ...input,
+        someField: 'hello'
+    };
+};
+```
+
+There are two built in libraries:
+
+* [dayjs](https://www.npmjs.com/package/dayjs) - for Date Manipulation
+* [big.js](https://www.npmjs.com/package/big.js) - for arbitrary-precision decimal arithmetic.
+
+### Expression Node
+
+The Expression node serves as a tool for transforming input objects into alternative objects using the Zen Expression
+Language. When specifying the output properties, each property requires a separate row. These rows are defined by two
+fields:
+
+- Key - qualified name of the output property
+- Value - value expressed through the Zen Expression Language
+
+Note: Any errors within the Expression node will bring the graph to a halt.
+
+<img width="960" alt="Decision Table" src="https://gorules.io/images/expression.png">
+
+### Decision Node
+
+The "Decision" node is designed to extend the capabilities of decision models. Its function is to invoke and reuse other
+decision models during execution.
+
+By incorporating the "Decision" node, developers can modularize decision logic, promoting reusability and
+maintainability in complex systems.
+
+## Support matrix
+
+| Arch            | Rust               | NodeJS             | Python             | Go                 |
+|:----------------|:-------------------|:-------------------|:-------------------|:-------------------|
+| linux-x64-gnu   | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| linux-arm64-gnu | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| darwin-x64      | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| darwin-arm64    | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| win32-x64-msvc  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+
+We do not support linux-musl currently.
+
+## Contribution
+
+JDM standard is growing and we need to keep tight control over its development and roadmap as there are number of
+companies that are using GoRules Zen-Engine and GoRules BRMS.
+For this reason we can't accept any code contributions at this moment, apart from help with documentation and additional
+tests.
+
+## License
+
+[MIT License]()
+

data/lib/zen-engine-ruby/version.rb

@@ -0,0 +1,3 @@
+module ZenRuby
+  VERSION = "0.0.1"
+end

data/lib/zen-engine-ruby.rb

@@ -0,0 +1,316 @@
+require "ffi"
+require "json"
+
+module ZenRuby
+  module LibC
+    extend FFI::Library
+    ffi_lib FFI::Library::LIBC
+
+    attach_function :strdup, [:string], :pointer
+  end
+
+  extend FFI::Library
+  
+  # Determine platform-specific library name and path
+  def self.find_library_path
+    os = case RbConfig::CONFIG['host_os']
+    when /darwin|mac os/i
+      'darwin'
+    when /linux/i
+      'linux'
+    when /mswin|mingw|windows/i
+      'windows'
+    else
+      raise "Unsupported operating system: #{RbConfig::CONFIG['host_os']}"
+    end
+
+    arch = case RbConfig::CONFIG['host_cpu']
+    when /arm64|aarch64/i
+      'arm64'
+    when /x86_64|amd64/i
+      'amd64'
+    else
+      raise "Unsupported architecture: #{RbConfig::CONFIG['host_cpu']}"
+    end
+
+    extension = os == 'windows' ? 'dll' : (os == 'darwin' ? 'dylib' : 'so')
+    lib_name = "libzen_ffi.#{extension}"
+    
+    # Get the gem's vendor path
+    gem_spec = Gem::Specification.find_by_name('zen-engine-ruby')
+    lib_path = File.join(gem_spec.gem_dir, 'vendor', "#{os}_#{arch}", lib_name)
+    
+    unless File.exist?(lib_path)
+      raise "Library not found for #{os}_#{arch} platform at #{lib_path}"
+    end
+    
+    lib_path
+  end
+
+  ffi_lib find_library_path
+
+  # typedef struct ZenDecisionLoaderResult {
+  #   char *content;
+  #   char *error;
+  # } ZenDecisionLoaderResult;
+  class ZenDecisionLoaderResult < FFI::Struct
+    layout :content, :pointer,
+           :error, :pointer
+  end
+
+  # typedef struct ZenCustomNodeResult {
+  #   char *content;
+  #   char *error;
+  # } ZenCustomNodeResult;
+  class ZenCustomNodeResult < FFI::Struct
+    layout :content, :pointer,
+           :error, :pointer
+  end
+
+  # typedef struct ZenEngineEvaluationOptions {
+  #   bool trace;
+  #   uint8_t max_depth;
+  # } ZenEngineEvaluationOptions;
+  class ZenEngineEvaluationOptions < FFI::Struct
+    layout :trace, :bool,
+           :max_depth, :uint8
+  end
+
+  # typedef struct ZenResult_c_char {
+  #   char *result;
+  #   uint8_t error;
+  #   char *details;
+  # } ZenResult_c_char;
+  class ZenResult_c_char < FFI::Struct
+    layout :result, :pointer,
+           :error, :uint8,
+           :details, :pointer
+  end
+
+  # typedef struct ZenResult_c_int {
+  #   int *result;
+  #   uint8_t error;
+  #   char *details;
+  # } ZenResult_c_int;
+  class ZenResult_c_int < FFI::Struct
+    layout :result, :pointer,
+           :error, :uint8,
+           :details, :pointer
+  end
+
+  # typedef struct ZenResult_ZenDecisionStruct {
+  #   struct ZenDecisionStruct *result;
+  #   uint8_t error;
+  #   char *details;
+  # } ZenResult_ZenDecisionStruct;
+  class ZenResult_ZenDecisionStruct < FFI::Struct
+    layout :result, :pointer,
+           :error, :uint8,
+           :details, :pointer
+  end
+
+  # typedef struct ZenDecisionLoaderResult (*ZenDecisionLoaderNativeCallback)(const char *key);
+  callback :zen_decision_loader_native_callback, [:string], ZenDecisionLoaderResult.by_value
+
+  # typedef struct ZenCustomNodeResult (*ZenCustomNodeNativeCallback)(const char *request);
+  callback :zen_custom_node_native_callback, [:string, :pointer], ZenCustomNodeResult.by_value
+
+  attach_function :zen_engine_new_native, 
+    [:zen_decision_loader_native_callback, :zen_custom_node_native_callback], 
+    :pointer
+
+  # void zen_engine_free(struct ZenEngineStruct *engine);
+  attach_function :zen_engine_free, [:pointer], :void
+
+  # struct ZenResult_c_char zen_engine_evaluate(const struct ZenEngineStruct *engine,
+  #                                         const char *key,
+  #                                         const char *context,
+  #                                         struct ZenEngineEvaluationOptions options);
+  attach_function :zen_engine_evaluate,
+                  [:pointer, :string, :string, ZenEngineEvaluationOptions.by_value],
+                  ZenResult_c_char.by_value
+
+  # struct ZenResult_ZenDecisionStruct zen_engine_get_decision(const struct ZenEngineStruct *engine,
+  #                                                          const char *key);
+  attach_function :zen_engine_get_decision,
+                  [:pointer, :string],
+                  ZenResult_ZenDecisionStruct.by_value
+
+  # struct ZenResult_ZenDecisionStruct zen_engine_create_decision(const struct ZenEngineStruct *engine,
+  #                                                            const char *content);
+  attach_function :zen_engine_create_decision,
+                  [:pointer, :string],
+                  ZenResult_ZenDecisionStruct.by_value
+
+  # struct ZenResult_c_char zen_decision_evaluate(const struct ZenDecisionStruct *decision,
+  #                                              const char *context_ptr,
+  #                                              struct ZenEngineEvaluationOptions options);
+  attach_function :zen_decision_evaluate,
+                  [:pointer, :string, ZenEngineEvaluationOptions.by_value],
+                  ZenResult_c_char.by_value
+
+  # struct ZenResult_c_char zen_evaluate_expression(const char *expression, const char *context);
+  attach_function :zen_evaluate_expression,
+                  [:string, :string],
+                  ZenResult_c_char.by_value
+
+  # struct ZenResult_c_int zen_evaluate_unary_expression(const char *expression, const char *context);
+  attach_function :zen_evaluate_unary_expression,
+                  [:string, :string],
+                  ZenResult_c_int.by_value
+
+  # struct ZenResult_c_char zen_evaluate_template(const char *template_, const char *context);
+  attach_function :zen_evaluate_template,
+                  [:string, :string],
+                  ZenResult_c_char.by_value
+
+  class Engine
+    def initialize(loader: nil, custom_handler: nil)
+      if loader
+        @loader_callback = Proc.new do |key|
+          content_json = loader.call(key)
+
+          loader_result = ZenDecisionLoaderResult.new
+          
+          # Allocate memory that won't be managed by Ruby
+          # (if we use MemoryPointer here, it'll cause double-free errors)
+          loader_result[:content] = LibC.strdup(content_json)
+          loader_result
+        end
+      end
+
+      if custom_handler
+        raise NotImplementedError, "Custom Node handler not implemented yet"
+        # @custom_node_callback = Proc.new do |request_str|
+        #   request = JSON.parse(request_str)
+        #   custom_handler.call(request).tap do |a|
+        #     puts a
+
+        #   end
+        # end
+      end
+
+      raw_pointer = ZenRuby.zen_engine_new_native(@loader_callback, @custom_node_callback)
+
+      # Because we need to do custom cleanup (via `zen_engine_free`) rather than
+      # just the usual `free` performed by MemoryPointer, we use AutoPointer.
+      @engine_ptr = FFI::AutoPointer.new(raw_pointer, ZenRuby.method(:zen_engine_free))
+    end
+
+    def evaluate(key, context, trace: false, max_depth: 10)
+      evaluation_options = ZenEngineEvaluationOptions.new
+      evaluation_options[:trace] = trace
+      evaluation_options[:max_depth] = max_depth
+
+      raw_result = ZenRuby.zen_engine_evaluate(@engine_ptr, key, context.to_json, evaluation_options)
+      ZenRuby::Result.from_raw_result(raw_result)
+    end
+
+    def evaluate!(key, context, trace: false, max_depth: 10)
+      ZenRuby.unwrap_result!(evaluate(key, context, trace:, max_depth:))
+    end
+
+    # Fetch a decision by providing a key to the decision JSON file. Uses
+    # the loader to fetch/read the actual JSON data for the Decision graph.
+    def get_decision(key)
+      # Caller is responsible for freeing: key and ZenResult.
+      raw_result = ZenRuby.zen_engine_get_decision(@engine_ptr, key)
+      ZenDecisionResult.from_raw_result(raw_result)
+    end
+
+    def get_decision!(key)
+      result = get_decision(key)
+      raise "Error getting decision for #{key}: #{result.error_code} #{result.details}" if result.error
+      result
+    end
+
+    # Create a decision from a JSON string directly; bypasses the loader.
+    def create_decision(content)
+      # Caller is responsible for freeing: content and ZenResult.
+      raw_result = ZenRuby.zen_engine_create_decision(@engine_ptr, content)
+      ZenDecisionResult.from_raw_result(raw_result)
+    end
+
+    # Create a decision from a JSON string directly; bypasses the loader.
+    def create_decision!(content)
+      result = create_decision(content)
+      raise "Error creating decision: #{result.error_code} #{result.details}" if result.error
+      result
+    end
+  end
+
+  ZenDecisionResult = Struct.new(:result, :error, :error_code, :details) do
+    def evaluate(context, trace: false, max_depth: 10)
+      if error
+        raise "Error evaluating decision for #{key}: #{error_code} #{details}"
+      end
+
+      evaluation_options = ZenEngineEvaluationOptions.new
+      evaluation_options[:trace] = trace
+      evaluation_options[:max_depth] = max_depth
+
+      raw_result = ZenRuby.zen_decision_evaluate(result, context.to_json, evaluation_options)
+      ZenRuby::Result.from_raw_result(raw_result)
+    end
+
+    def evaluate!(...)
+      ZenRuby.unwrap_result!(evaluate(...))
+    end
+
+    def self.from_raw_result(raw_result)
+      if raw_result[:error] == 0
+        ZenDecisionResult.new(raw_result[:result], false, 0, nil)
+      else
+        ZenDecisionResult.new(nil, true, raw_result[:error], raw_result[:details].null? ? nil : raw_result[:details].read_string)
+      end
+    end
+  end
+
+  Result = Struct.new(:result, :error, :error_code, :details) do
+    def self.from_raw_result(raw_result)
+      if raw_result[:error] == 0
+        json_string = raw_result[:result].read_string
+        ZenRuby::Result.new(JSON.parse(json_string), false, 0, nil)
+      else
+        ZenRuby::Result.new(nil, true, raw_result[:error], raw_result[:details].read_string)
+      end
+    end
+  end
+
+  def self.unwrap_result!(result)
+    raise "Error evaluating: #{result.error_code} #{result.details}" if result.error
+    result.result
+  end
+
+  def self.evaluate_expression(expression, context)
+    raw_result = ZenRuby.zen_evaluate_expression(expression, context.to_json)
+    ZenRuby::Result.from_raw_result(raw_result)
+  end
+
+  def self.evaluate_expression!(expression, context)
+    ZenRuby.unwrap_result!(evaluate_expression(expression, context))
+  end
+
+  def self.evaluate_unary_expression(expression, context)
+    raw_result = ZenRuby.zen_evaluate_unary_expression(expression, context.to_json)
+    if raw_result[:error] == 0
+      value = raw_result[:result].read(:int)
+      ZenRuby::Result.new(value == 1, false, 0, nil)
+    else
+      ZenRuby::Result.new(nil, true, raw_result[:error], raw_result[:details].read_string)
+    end
+  end
+
+  def self.evaluate_unary_expression!(expression, context)
+    ZenRuby.unwrap_result!(evaluate_unary_expression(expression, context))
+  end
+
+  def self.render_template(template, context)
+    raw_result = ZenRuby.zen_evaluate_template(template, context.to_json)
+    ZenRuby::Result.from_raw_result(raw_result)
+  end
+
+  def self.render_template!(template, context)
+    ZenRuby.unwrap_result!(render_template(template, context))
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: zen-engine-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: arm64-linux
+authors:
+- Alex Matchneer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+description: Ruby FFI bindings for the Zen library
+email:
+- amatchneer@futureproofretail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zen-engine-ruby.rb
+- lib/zen-engine-ruby/version.rb
+- vendor/linux_arm64/libzen_ffi.so
+homepage: https://github.com/FutureProofRetail/zen-engine-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Ruby bindings for GoRules ZEN engine
+test_files: []