monty-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2fb3f19f561ec5c1c423e4f285717613ee92d9007cfb7ca0e9a87c00f912449b
+  data.tar.gz: 2ecf1a8636e3945f82677cbed4a942f47026c89be25ace25466fd969ab016ad2
+SHA512:
+  metadata.gz: ebbe528825cd7b82728b125a28b303134526c3dbc3edb9afeec90f95041dafb36d542e4946bc112c92659c46a447babdc93548cd1082db6b4e124f63fbb7a0a4
+  data.tar.gz: 7e094af7174ecceea7dbe88f4a208a446e39446d2a313bbe48819db263448687eb7b189308a2ece9e5e8652752dab6c0cdb1f1e0143ae65f6dac3781e590b92b

data/Cargo.toml

@@ -0,0 +1,9 @@
+[workspace]
+members = ["ext/monty"]
+resolver = "2"
+
+[profile.release]
+strip = true
+
+[profile.dev]
+strip = true

data/README.md

@@ -0,0 +1,251 @@
+# Monty Ruby
+
+Ruby bindings for [Monty](https://github.com/pydantic/monty), a minimal and secure Python interpreter written in Rust by [Pydantic](https://pydantic.dev). Built with [Magnus](https://github.com/matsadler/magnus).
+
+## What is Monty?
+
+[Monty](https://github.com/pydantic/monty) is a Python interpreter designed specifically for AI agents. Unlike CPython, it prioritizes security and embeddability over compatibility with the full Python ecosystem.
+
+Key properties of the Monty interpreter:
+
+- **Sub-microsecond startup** — no VM boot, no module loading, ready instantly
+- **Strict sandboxing** — no filesystem, no network, no environment variable access by default
+- **CPython-comparable performance** — not a toy interpreter
+- **External function mediation** — all I/O is controlled by the host application
+- **Snapshot/resume** — serialize execution state mid-flight and restore it later
+- **Resource limits** — cap memory, allocations, execution time, and recursion depth
+
+Monty supports a practical Python subset: functions, closures, async/await, type hints, dataclasses, list/dict/set comprehensions, and exceptions. It does not support arbitrary classes (coming soon), match statements, or the Python standard library beyond `sys`, `typing`, `asyncio`, `dataclasses`, and `json`.
+
+## Why Ruby bindings?
+
+If you're building AI agents, tool-use pipelines, or code evaluation features in Ruby, Monty lets you safely execute LLM-generated Python without:
+
+- **Containers or VMs** — no Docker, no subprocess spawning, no cold starts
+- **Security risks** — the interpreter can't touch the filesystem, network, or env vars unless you explicitly allow it via external functions
+- **Language mismatch** — your orchestration stays in Ruby while computation happens in Python
+
+### Use cases
+
+- **AI agent tool execution** — LLMs generate Python code; your Ruby app runs it safely and returns the result
+- **Computed fields and expressions** — let users write Python expressions that your app evaluates (e.g. spreadsheet formulas, data transformations, scoring functions)
+- **Sandboxed scripting** — embed a user-facing scripting language in your Ruby application with deterministic resource limits
+- **Polyglot data pipelines** — bridge Python's data manipulation idioms (list comprehensions, dict operations) into a Ruby-native workflow
+- **Code evaluation APIs** — build "run this code" endpoints without worrying about arbitrary code execution
+
+
+> [!NOTE] Experimental gem
+
+This gem was created as an experiment to see how Opus 4.6 and ChatGPT Codex 5.3 would be able to take the Monty crate from the Pydantic team and bind it to Ruby. All of the code in this gem has been generated by AI Agents.
+
+## How the bindings work
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Ruby application                                   │
+│                                                     │
+│   Monty::Run.new(python_code, inputs: ["x"])        │
+│   run.call(42)  # => result                         │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│  Ruby wrappers  (lib/monty/)                        │
+│   - Keyword arguments, blocks, idiomatic Ruby API   │
+│   - call_with_externals { |fn| ... }                │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│  Magnus FFI layer  (ext/monty/src/)                 │
+│   - #[magnus::wrap] structs → Ruby classes          │
+│   - MontyObject ↔ Ruby value conversion             │
+│   - Error mapping: MontyException → Monty::Error    │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│  Monty interpreter  (Rust crate)                    │
+│   - MontyRun: parse once, execute many times        │
+│   - Sandboxed VM with resource tracking             │
+│   - External function call / snapshot / resume      │
+└─────────────────────────────────────────────────────┘
+```
+
+The native extension is compiled as a C-compatible dynamic library (`cdylib`) via [rb-sys](https://github.com/oxidize-rb/rb-sys) and [Magnus](https://github.com/matsadler/magnus). No tokio runtime is needed — Monty's execution is synchronous from Rust's perspective (Python `async/await` is handled internally by the interpreter's cooperative state machine).
+
+**Value conversion** happens at the boundary: Ruby objects are converted to `MontyObject` variants on the way in, and converted back to Ruby objects on the way out. This means there's no shared mutable state between Ruby and Python — each call is a clean value-in, value-out exchange.
+
+**External functions** allow Python code to call back into Ruby. When the interpreter hits an external function call, it pauses execution and returns a `Monty::FunctionCall` to the host. The host resolves the call in Ruby and resumes the interpreter with the result. This is how you give sandboxed Python controlled access to I/O, databases, APIs, or anything else.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "monty-rb"
+```
+
+Or install directly:
+
+```sh
+gem install monty-rb
+```
+
+Requires Rust 1.90+ for compilation.
+
+## Usage
+
+### Simple Execution
+
+```ruby
+require "monty"
+
+# Evaluate a Python expression
+run = Monty::Run.new("x + y", inputs: ["x", "y"])
+run.call(1, 2) # => 3
+
+# Python functions
+code = <<~PYTHON
+  def factorial(n):
+      if n <= 1:
+          return 1
+      return n * factorial(n - 1)
+
+  factorial(n)
+PYTHON
+
+run = Monty::Run.new(code, inputs: ["n"])
+run.call(10) # => 3628800
+
+# Reusable — parse once, call many times
+run = Monty::Run.new("x * 2", inputs: ["x"])
+run.call(5)   # => 10
+run.call(21)  # => 42
+```
+
+### Data Type Conversion
+
+Ruby values are automatically converted to Python and back:
+
+| Ruby | Python | Ruby |
+|------|--------|------|
+| `nil` | `None` | `nil` |
+| `true` / `false` | `True` / `False` | `true` / `false` |
+| `Integer` | `int` | `Integer` |
+| `Float` | `float` | `Float` |
+| `String` | `str` | `String` |
+| `Array` | `list` | `Array` |
+| `Hash` | `dict` | `Hash` |
+| `Symbol` | `str` | `String` |
+
+Tuples are returned as frozen Arrays. Nested structures are converted recursively.
+
+### Capturing Output
+
+```ruby
+run = Monty::Run.new("print('hello')\n42")
+result = run.call(capture_output: true)
+result[:result] # => 42
+result[:output] # => "hello\n"
+```
+
+### Resource Limits
+
+Prevent runaway code from consuming unbounded resources:
+
+```ruby
+run = Monty::Run.new("x ** x ** x", inputs: ["x"])
+run.call(100, limits: {
+  max_duration: 2.0,        # seconds
+  max_memory: 10_485_760,   # bytes
+  max_allocations: 100_000,
+  max_recursion_depth: 500
+})
+# Raises Monty::ResourceError if any limit is exceeded
+```
+
+### External Function Calls
+
+Monty scripts can call external functions that you implement in Ruby. This is the primary mechanism for giving sandboxed Python controlled access to external resources:
+
+```ruby
+code = <<~PYTHON
+  response = fetch("https://api.example.com/data")
+  response.upper()
+PYTHON
+
+run = Monty::Run.new(code, external_functions: ["fetch"])
+
+# Block-based API (recommended)
+result = run.call_with_externals do |call|
+  case call.function_name
+  when "fetch"
+    Net::HTTP.get(URI(call.args[0]))
+  end
+end
+
+# Capture output and apply limits
+result = run.call_with_externals(capture_output: true, limits: { max_duration: 2.0 }) do |call|
+  case call.function_name
+  when "fetch"
+    Net::HTTP.get(URI(call.args[0]))
+  end
+end
+# result[:result] => Python return value
+# result[:output] => captured stdout
+
+# Manual step-through API
+run = Monty::Run.new(code, external_functions: ["fetch"])
+progress = run.start
+
+while progress.is_a?(Monty::FunctionCall)
+  result = handle_function(progress.function_name, progress.args)
+  progress = progress.resume(result)
+end
+
+final_value = progress.value
+```
+
+### Serialization
+
+`Monty::Run` instances can be serialized for caching or storage. Since parsing is separated from execution, you can parse once and reuse across requests:
+
+```ruby
+run = Monty::Run.new("x * 2", inputs: ["x"])
+bytes = run.dump
+
+# Later, or in another process...
+restored = Monty::Run.load(bytes)
+restored.call(21) # => 42
+```
+
+## Error Handling
+
+```ruby
+# Monty::Error         - base error class (< StandardError)
+# Monty::SyntaxError   - Python syntax errors
+# Monty::ResourceError - resource limit exceeded
+# Monty::ConsumedError - using a consumed Run/FunctionCall
+
+begin
+  run = Monty::Run.new("1 / 0")
+  run.call
+rescue Monty::Error => e
+  puts e.message
+end
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile  # build native extension
+bundle exec rake spec     # run tests
+bundle exec rake          # compile + test
+```
+
+## References
+
+- [Monty](https://github.com/pydantic/monty) — the Rust interpreter this gem wraps
+- [Magnus](https://github.com/matsadler/magnus) — Rust ↔ Ruby bindings framework
+- [rb-sys](https://github.com/oxidize-rb/rb-sys) — Ruby native extension build system for Rust
+- [Pydantic](https://pydantic.dev) — the team behind Monty
+
+## License
+
+MIT

data/ext/monty/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "monty"
+version = "0.1.0"
+edition = "2021"
+publish = false
+license = "MIT"
+description = "Ruby bindings for Monty Python interpreter"
+
+[lib]
+name = "monty"
+crate-type = ["cdylib"]
+
+[dependencies]
+monty-lang = { package = "monty", git = "https://github.com/pydantic/monty.git" }
+magnus = { version = "0.8", features = ["rb-sys"] }
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+num-bigint = "0.4"

data/ext/monty/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("monty/monty")

data/ext/monty/src/errors.rs

@@ -0,0 +1,130 @@
+use magnus::{Error, ExceptionClass, Module, Ruby};
+use std::cell::RefCell;
+
+thread_local! {
+    static MONTY_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static SYNTAX_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static RESOURCE_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+    static CONSUMED_ERROR: RefCell<Option<ExceptionClass>> = const { RefCell::new(None) };
+}
+
+pub fn define_exceptions(ruby: &Ruby, module: &magnus::RModule) -> Result<(), Error> {
+    let standard_error = ruby.exception_standard_error();
+
+    let monty_error = module.define_error("Error", standard_error)?;
+    MONTY_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(monty_error);
+    });
+
+    let syntax_error = module.define_error("SyntaxError", monty_error)?;
+    SYNTAX_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(syntax_error);
+    });
+
+    let resource_error = module.define_error("ResourceError", monty_error)?;
+    RESOURCE_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(resource_error);
+    });
+
+    let consumed_error = module.define_error("ConsumedError", monty_error)?;
+    CONSUMED_ERROR.with(|cell| {
+        *cell.borrow_mut() = Some(consumed_error);
+    });
+
+    Ok(())
+}
+
+pub fn monty_error(message: String) -> Error {
+    MONTY_ERROR.with(|cell| {
+        let class = cell.borrow();
+        match class.as_ref() {
+            Some(cls) => Error::new(*cls, message),
+            None => {
+                let ruby = Ruby::get().expect("Ruby runtime not available");
+                Error::new(ruby.exception_runtime_error(), message)
+            },
+        }
+    })
+}
+
+pub fn syntax_error(message: String) -> Error {
+    SYNTAX_ERROR.with(|cell| {
+        let class = cell.borrow();
+        match class.as_ref() {
+            Some(cls) => Error::new(*cls, message),
+            None => {
+                let ruby = Ruby::get().expect("Ruby runtime not available");
+                Error::new(ruby.exception_runtime_error(), message)
+            },
+        }
+    })
+}
+
+pub fn resource_error(message: String) -> Error {
+    RESOURCE_ERROR.with(|cell| {
+        let class = cell.borrow();
+        match class.as_ref() {
+            Some(cls) => Error::new(*cls, message),
+            None => {
+                let ruby = Ruby::get().expect("Ruby runtime not available");
+                Error::new(ruby.exception_runtime_error(), message)
+            },
+        }
+    })
+}
+
+pub fn consumed_error() -> Error {
+    CONSUMED_ERROR.with(|cell| {
+        let class = cell.borrow();
+        match class.as_ref() {
+            Some(cls) => Error::new(
+                *cls,
+                "this object has been consumed and can no longer be used",
+            ),
+            None => {
+                let ruby = Ruby::get().expect("Ruby runtime not available");
+                Error::new(
+                    ruby.exception_runtime_error(),
+                    "this object has been consumed and can no longer be used",
+                )
+            }
+        }
+    })
+}
+
+pub fn map_monty_exception(exc: monty_lang::MontyException) -> Error {
+    let summary = exc.summary();
+
+    // Check if it's a syntax error
+    if exc.exc_type() == monty_lang::ExcType::SyntaxError {
+        return syntax_error(summary);
+    }
+
+    monty_error(summary)
+}
+
+pub fn map_resource_error(err: monty_lang::ResourceError) -> Error {
+    let message = match err {
+        monty_lang::ResourceError::Allocation { limit, count } => {
+            format!("allocation limit exceeded: {count} allocations (limit: {limit})")
+        }
+        monty_lang::ResourceError::Time { limit, elapsed } => {
+            format!(
+                "time limit exceeded: {:.2}s elapsed (limit: {:.2}s)",
+                elapsed.as_secs_f64(),
+                limit.as_secs_f64()
+            )
+        }
+        monty_lang::ResourceError::Memory { limit, used } => {
+            format!("memory limit exceeded: {used} bytes used (limit: {limit})")
+        }
+        monty_lang::ResourceError::Recursion { limit, depth } => {
+            format!("recursion limit exceeded: depth {depth} (limit: {limit})")
+        }
+        monty_lang::ResourceError::Exception(exc) => {
+            return map_monty_exception(exc);
+        }
+    };
+
+    resource_error(message)
+}

data/ext/monty/src/lib.rs

@@ -0,0 +1,20 @@
+use magnus::{Error, Ruby};
+
+#[allow(dead_code)]
+mod errors;
+mod monty_object;
+mod monty_run;
+mod resource_limits;
+mod run_progress;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Monty")?;
+
+    errors::define_exceptions(ruby, &module)?;
+    resource_limits::define_resource_limits_class(ruby, &module)?;
+    monty_run::define_run_class(ruby, &module)?;
+    run_progress::define_progress_classes(ruby, &module)?;
+
+    Ok(())
+}

data/ext/monty/src/monty_object.rs

@@ -0,0 +1,211 @@
+use magnus::value::ReprValue;
+use magnus::{Error, RArray, RHash, Ruby, TryConvert, Value};
+use monty_lang::MontyObject;
+
+/// Convert a Ruby value to a MontyObject
+pub fn ruby_to_monty(val: Value) -> Result<MontyObject, Error> {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+
+    if val.is_nil() {
+        return Ok(MontyObject::None);
+    }
+
+    // Check for booleans by class name
+    if let Some(b) = detect_bool(val) {
+        return Ok(MontyObject::Bool(b));
+    }
+
+    // Integer
+    if val.is_kind_of(ruby.class_integer()) {
+        // Try i64 first, fall back to BigInt via string
+        if let Ok(i) = i64::try_convert(val) {
+            return Ok(MontyObject::Int(i));
+        }
+        // Large integer: convert via string representation
+        let s: String = val.funcall("to_s", ())?;
+        let big = s
+            .parse::<num_bigint::BigInt>()
+            .map_err(|e| Error::new(ruby.exception_arg_error(), format!("invalid integer: {e}")))?;
+        return Ok(MontyObject::BigInt(big));
+    }
+
+    // Float
+    if val.is_kind_of(ruby.class_float()) {
+        let f: f64 = f64::try_convert(val)?;
+        return Ok(MontyObject::Float(f));
+    }
+
+    // String
+    if val.is_kind_of(ruby.class_string()) {
+        let s: String = String::try_convert(val)?;
+        return Ok(MontyObject::String(s));
+    }
+
+    // Symbol -> String
+    if val.is_kind_of(ruby.class_symbol()) {
+        let s: String = val.funcall("to_s", ())?;
+        return Ok(MontyObject::String(s));
+    }
+
+    // Array -> List
+    if val.is_kind_of(ruby.class_array()) {
+        let arr: RArray = RArray::try_convert(val)?;
+        let mut items = Vec::with_capacity(arr.len());
+        for i in 0..arr.len() {
+            let item: Value = arr.entry(i as isize)?;
+            items.push(ruby_to_monty(item)?);
+        }
+        return Ok(MontyObject::List(items));
+    }
+
+    // Hash -> Dict
+    if val.is_kind_of(ruby.class_hash()) {
+        let hash: RHash = RHash::try_convert(val)?;
+        let pairs = hash_to_pairs(hash)?;
+        return Ok(MontyObject::dict(pairs));
+    }
+
+    Err(Error::new(
+        ruby.exception_type_error(),
+        format!(
+            "cannot convert {} to a Python object",
+            val.class().inspect()
+        ),
+    ))
+}
+
+/// Convert a MontyObject to a Ruby value
+pub fn monty_to_ruby(obj: MontyObject) -> Result<Value, Error> {
+    let ruby = Ruby::get().expect("Ruby runtime not available");
+
+    match obj {
+        MontyObject::None => Ok(ruby.qnil().as_value()),
+        MontyObject::Bool(b) => {
+            if b {
+                Ok(ruby.qtrue().as_value())
+            } else {
+                Ok(ruby.qfalse().as_value())
+            }
+        }
+        MontyObject::Int(i) => Ok(ruby.integer_from_i64(i).as_value()),
+        MontyObject::BigInt(bi) => {
+            let s = bi.to_string();
+            let ruby_str = ruby.str_new(&s);
+            ruby_str.funcall("to_i", ())
+        }
+        MontyObject::Float(f) => Ok(ruby.float_from_f64(f).as_value()),
+        MontyObject::String(s) => Ok(ruby.str_new(&s).as_value()),
+        MontyObject::Bytes(b) => {
+            let s = ruby.str_from_slice(&b);
+            s.funcall::<_, _, Value>("force_encoding", ("ASCII-8BIT",))?;
+            Ok(s.as_value())
+        }
+        MontyObject::List(items) => {
+            let arr = ruby.ary_new_capa(items.len());
+            for item in items {
+                let val = monty_to_ruby(item)?;
+                arr.push(val)?;
+            }
+            Ok(arr.as_value())
+        }
+        MontyObject::Tuple(items) => {
+            let arr = ruby.ary_new_capa(items.len());
+            for item in items {
+                let val = monty_to_ruby(item)?;
+                arr.push(val)?;
+            }
+            arr.funcall::<_, _, Value>("freeze", ())?;
+            Ok(arr.as_value())
+        }
+        MontyObject::NamedTuple {
+            field_names,
+            values,
+            ..
+        } => {
+            let hash = ruby.hash_new();
+            for (name, value) in field_names.into_iter().zip(values.into_iter()) {
+                let key = ruby.str_new(&name);
+                let val = monty_to_ruby(value)?;
+                hash.aset(key, val)?;
+            }
+            Ok(hash.as_value())
+        }
+        MontyObject::Dict(pairs) => {
+            let hash = ruby.hash_new();
+            for (k, v) in pairs.into_iter() {
+                let key = monty_to_ruby(k)?;
+                let val = monty_to_ruby(v)?;
+                hash.aset(key, val)?;
+            }
+            Ok(hash.as_value())
+        }
+        MontyObject::Set(items) | MontyObject::FrozenSet(items) => {
+            let arr = ruby.ary_new_capa(items.len());
+            for item in items {
+                let val = monty_to_ruby(item)?;
+                arr.push(val)?;
+            }
+            Ok(arr.as_value())
+        }
+        MontyObject::Dataclass { attrs, .. } => {
+            let hash = ruby.hash_new();
+            for (k, v) in attrs.into_iter() {
+                let key = monty_to_ruby(k)?;
+                let val = monty_to_ruby(v)?;
+                hash.aset(key, val)?;
+            }
+            Ok(hash.as_value())
+        }
+        MontyObject::Ellipsis => {
+            let sym = ruby.to_symbol("ellipsis");
+            Ok(sym.as_value())
+        }
+        MontyObject::Type(t) => {
+            let repr = format!("{t:?}");
+            Ok(ruby.str_new(&repr).as_value())
+        }
+        MontyObject::BuiltinFunction(f) => {
+            let repr = format!("{f:?}");
+            Ok(ruby.str_new(&repr).as_value())
+        }
+        MontyObject::Path(s) => Ok(ruby.str_new(&s).as_value()),
+        MontyObject::Repr(s) => Ok(ruby.str_new(&s).as_value()),
+        MontyObject::Cycle(_, s) => Ok(ruby.str_new(&s).as_value()),
+        MontyObject::Exception { exc_type, arg } => {
+            let msg = arg.unwrap_or_else(|| format!("{exc_type:?}"));
+            Err(crate::errors::monty_error(msg))
+        }
+    }
+}
+
+/// Convert a Ruby Array of values to Vec<MontyObject>
+pub fn ruby_array_to_monty_vec(arr: RArray) -> Result<Vec<MontyObject>, Error> {
+    let mut result = Vec::with_capacity(arr.len());
+    for i in 0..arr.len() {
+        let item: Value = arr.entry(i as isize)?;
+        result.push(ruby_to_monty(item)?);
+    }
+    Ok(result)
+}
+
+/// Detect Ruby true/false by querying the class name
+fn detect_bool(val: Value) -> Option<bool> {
+    let class_val: Value = val.funcall("class", ()).ok()?;
+    let name: String = class_val.funcall("name", ()).ok()?;
+    match name.as_str() {
+        "TrueClass" => Some(true),
+        "FalseClass" => Some(false),
+        _ => None,
+    }
+}
+
+fn hash_to_pairs(hash: RHash) -> Result<Vec<(MontyObject, MontyObject)>, Error> {
+    let keys: RArray = hash.funcall("keys", ())?;
+    let mut pairs = Vec::with_capacity(keys.len());
+    for i in 0..keys.len() {
+        let key: Value = keys.entry(i as isize)?;
+        let val: Value = hash.aref(key)?;
+        pairs.push((ruby_to_monty(key)?, ruby_to_monty(val)?));
+    }
+    Ok(pairs)
+}