ruby-mana 0.4.0 → 0.5.1

data/lib/mana/engines/python.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+begin
+  require "pycall"
+rescue LoadError
+  raise LoadError, "pycall gem is required for Python support. Add `gem 'pycall'` to your Gemfile."
+end
+
+require "json"
+
+module Mana
+  module Engines
+    class Python < Base
+      # Python helper code injected once per namespace.
+      # Sets up weak-ref tracking so when Python drops a reference to a
+      # complex Ruby object, the ObjectRegistry is notified.
+      PY_GC_HELPER = <<~PYTHON
+        import weakref as _mana_wr
+        import builtins as _mana_bi
+        _mana_bi._mana_weakref = _mana_wr
+
+        class __ManaRef:
+            """Weak-ref release notifier for Ruby objects passed to Python."""
+            _release_fn = None
+            _instances = {}
+
+            @classmethod
+            def set_release_fn(cls, fn):
+                cls._release_fn = fn
+
+            @classmethod
+            def track(cls, ref_id, obj):
+                """Track a Ruby object. When Python GC collects it, notify Ruby."""
+                import builtins
+                _wr = builtins._mana_weakref
+                try:
+                    ref = _wr.ref(obj, lambda r, rid=ref_id: cls._release(rid))
+                    cls._instances[ref_id] = ref
+                except TypeError:
+                    # Some objects can't be weakly referenced; skip them
+                    pass
+
+            @classmethod
+            def _release(cls, ref_id):
+                cls._instances.pop(ref_id, None)
+                if cls._release_fn:
+                    try:
+                        cls._release_fn(ref_id)
+                    except Exception:
+                        pass
+
+            @classmethod
+            def release_all(cls):
+                for ref_id in list(cls._instances.keys()):
+                    cls._release(ref_id)
+      PYTHON
+
+      # Thread-local persistent Python state
+      # PyCall shares a single Python interpreter per process,
+      # but we track our own variable namespace
+      def self.namespace
+        Thread.current[:mana_py_namespace] ||= create_namespace
+      end
+
+      def self.create_namespace
+        PyCall.eval("dict()")
+      end
+
+      def self.reset!
+        ns = Thread.current[:mana_py_namespace]
+        if ns
+          begin
+            mana_ref = ns["__ManaRef"]
+            mana_ref.release_all if mana_ref
+          rescue => e
+            # ignore
+          end
+          PyCall.exec("pass") # ensure interpreter is alive
+          Thread.current[:mana_py_namespace] = nil
+        end
+        Thread.current[:mana_py_gc_injected] = nil
+        ObjectRegistry.reset!
+      end
+
+      def execute(code)
+        ns = self.class.namespace
+
+        # 0. Inject GC helper (once per namespace)
+        inject_gc_helper(ns)
+
+        # 1. Inject Ruby variables into Python namespace
+        inject_ruby_vars(ns, code)
+
+        # 2. Inject the Ruby bridge for Python->Ruby callbacks
+        inject_ruby_bridge(ns)
+
+        # 3. Execute Python code in the namespace
+        PyCall.exec(code, locals: ns)
+
+        # 4. Extract declared variables back to Ruby
+        extract_py_vars(ns, code)
+
+        # Return the last expression value if possible
+        begin
+          ns["result"]
+        rescue
+          nil
+        end
+      rescue PyCall::PyError => e
+        raise Mana::Error, "Python execution error: #{e.message}"
+      rescue ArgumentError => e
+        raise Mana::Error, "Python execution error: #{e.message}"
+      end
+
+      private
+
+      def inject_gc_helper(ns)
+        return if Thread.current[:mana_py_gc_injected]
+
+        PyCall.exec(PY_GC_HELPER, locals: ns)
+
+        # Wire up the release callback: when Python GC collects a tracked object,
+        # __ManaRef calls this proc to release it from the Ruby ObjectRegistry.
+        registry = ObjectRegistry.current
+        release_fn = proc { |ref_id| registry.release(ref_id.to_i) }
+        mana_ref = ns["__ManaRef"]
+        mana_ref.set_release_fn(release_fn)
+
+        Thread.current[:mana_py_gc_injected] = true
+      end
+
+      def inject_ruby_vars(ns, code)
+        @binding.local_variables.each do |var_name|
+          value = @binding.local_variable_get(var_name)
+          serialized = serialize_for_py(value)
+          begin
+            ns[var_name.to_s] = serialized
+          rescue => e
+            next
+          end
+        end
+      end
+
+      # Inject a `ruby` bridge into the Python namespace.
+      #
+      # The bridge is a Ruby object with method_missing that proxies calls
+      # back to the Ruby binding. PyCall automatically wraps it so Python
+      # can call methods directly:
+      #
+      #   ruby.method_name(arg1, arg2)  -- call a Ruby method on the receiver
+      #   ruby.read("var")              -- read a Ruby local variable
+      #   ruby.write("var", value)      -- write a Ruby local variable
+      #   ruby.call_proc("name", args)  -- call a local proc/lambda by name
+      #
+      # Ruby objects (including the binding receiver) can also be injected
+      # directly and called from Python -- PyCall handles the wrapping.
+      def inject_ruby_bridge(ns)
+        ns["ruby"] = RubyBridge.new(@binding)
+      end
+
+      def extract_py_vars(ns, code)
+        declared_vars = extract_declared_vars(code)
+        declared_vars.each do |var_name|
+          next if var_name == "ruby" # skip the bridge object
+          begin
+            value = ns[var_name]
+            deserialized = deserialize_py(value)
+            write_var(var_name, deserialized)
+          rescue => e
+            next
+          end
+        end
+      end
+
+      def extract_declared_vars(code)
+        vars = []
+        # Match Python assignments: x = ..., but not x == ... or x += ...
+        code.scan(/^(\w+)\s*=[^=]/).each { |m| vars << m[0] }
+        # Also match augmented assignments: x += ..., x -= ...
+        code.scan(/^(\w+)\s*[+\-*\/]?=/).each { |m| vars << m[0] }
+        vars.uniq
+      end
+
+      # Serialize Ruby values for Python injection.
+      # Simple types are copied. Complex objects are passed directly via PyCall
+      # (which wraps them so Python can call their methods) AND registered in
+      # the ObjectRegistry for lifecycle tracking + GC notification.
+      def serialize_for_py(value)
+        case value
+        when Numeric, String, TrueClass, FalseClass, NilClass
+          value
+        when Symbol
+          value.to_s
+        when Array
+          value.map { |v| serialize_for_py(v) }
+        when Hash
+          value.each_with_object({}) do |(k, v), h|
+            key = k.is_a?(Symbol) ? k.to_s : k
+            h[key] = serialize_for_py(v)
+          end
+        when Proc, Method
+          ref_id = ObjectRegistry.current.register(value)
+          track_in_python(ref_id, value)
+          value
+        else
+          ref_id = ObjectRegistry.current.register(value)
+          track_in_python(ref_id, value)
+          value
+        end
+      end
+
+      # Tell the Python __ManaRef tracker to watch this object via weakref.
+      def track_in_python(ref_id, value)
+        ns = self.class.namespace
+        begin
+          mana_ref = ns["__ManaRef"]
+          mana_ref.track(ref_id, value) if mana_ref
+        rescue => e
+          # Non-fatal: some objects can't be weakly referenced in Python
+        end
+      end
+
+      def deserialize_py(value)
+        if defined?(PyCall::PyObjectWrapper) && value.is_a?(PyCall::PyObjectWrapper)
+          begin
+            value.to_a rescue value.to_s
+          rescue
+            value.to_s
+          end
+        else
+          value
+        end
+      end
+    end
+
+    # Bridge object injected as `ruby` in the Python namespace.
+    # Enables Python->Ruby callbacks via method_missing.
+    #
+    # Python usage:
+    #   ruby.some_method(arg1, arg2)  -- calls method on binding receiver
+    #   ruby.read("var_name")         -- reads a Ruby local variable
+    #   ruby.write("var_name", val)   -- writes a Ruby local variable
+    #   ruby.call_proc("name", args)  -- calls a local proc/lambda by name
+    class RubyBridge
+      def initialize(caller_binding)
+        @binding = caller_binding
+        @receiver = caller_binding.receiver
+      end
+
+      # Read a Ruby local variable
+      def read(name)
+        name = name.to_s.to_sym
+        if @binding.local_variables.include?(name)
+          @binding.local_variable_get(name)
+        else
+          raise NameError, "undefined Ruby variable '#{name}'"
+        end
+      end
+
+      # Write a Ruby local variable
+      def write(name, value)
+        @binding.local_variable_set(name.to_s.to_sym, value)
+      end
+
+      # Explicitly call a local proc/lambda by name
+      def call_proc(name, *args)
+        name = name.to_s.to_sym
+        if @binding.local_variables.include?(name)
+          val = @binding.local_variable_get(name)
+          if val.respond_to?(:call)
+            return val.call(*args)
+          end
+        end
+        raise NoMethodError, "no callable '#{name}' in Ruby scope"
+      end
+
+      # Proxy unknown method calls to the binding receiver.
+      # This lets Python do: ruby.some_method(args)
+      def method_missing(name, *args)
+        name_s = name.to_s
+
+        # First check local procs/lambdas
+        name_sym = name_s.to_sym
+        if @binding.local_variables.include?(name_sym)
+          val = @binding.local_variable_get(name_sym)
+          return val.call(*args) if val.respond_to?(:call)
+        end
+
+        # Then try the receiver
+        if @receiver.respond_to?(name_s)
+          return @receiver.public_send(name_s, *args)
+        end
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        name_s = name.to_s
+        name_sym = name_s.to_sym
+
+        # Check local callables
+        if @binding.local_variables.include?(name_sym)
+          val = @binding.local_variable_get(name_sym)
+          return true if val.respond_to?(:call)
+        end
+
+        # Check receiver (public methods only)
+        return true if @receiver.respond_to?(name_s)
+
+        super
+      end
+    end
+  end
+end

data/lib/mana/engines/ruby_eval.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mana
+  module Engines
+    class Ruby < Base
+      def execute(code)
+        eval(code, @binding)
+      end
+    end
+  end
+end

data/lib/mana/object_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Mana
+  # Thread-local registry for cross-engine object references.
+  #
+  # When a complex Ruby object is passed to JS/Python, it gets registered here
+  # with a unique integer ID. The foreign engine holds a proxy with that ID and
+  # routes method calls back through the bidirectional channel.
+  #
+  # Thread-local so each engine context (which is also thread-local) has its own
+  # isolated set of references.
+  class ObjectRegistry
+    attr_reader :objects
+
+    def initialize
+      @objects = {}
+      @next_id = 1
+      @release_callbacks = []
+    end
+
+    # Store an object and return its reference ID.
+    # If the same object is already registered, return the existing ID.
+    def register(obj)
+      # Check if already registered (by object_id for identity, not equality)
+      @objects.each do |id, entry|
+        return id if entry[:object].equal?(obj)
+      end
+
+      id = @next_id
+      @next_id += 1
+      @objects[id] = { object: obj, type: obj.class.name }
+      id
+    end
+
+    # Retrieve an object by its reference ID.
+    def get(id)
+      entry = @objects[id]
+      entry ? entry[:object] : nil
+    end
+
+    # Register a callback invoked when any reference is released.
+    # The callback receives (id, entry) where entry is { object:, type: }.
+    def on_release(&block)
+      @release_callbacks << block
+    end
+
+    # Release a reference. Returns true if it existed.
+    # Fires registered on_release callbacks with the id and entry.
+    def release(id)
+      entry = @objects.delete(id)
+      return false unless entry
+
+      @release_callbacks.each do |cb|
+        cb.call(id, entry)
+      rescue => e
+        # Don't let callback errors break the release
+      end
+      true
+    end
+
+    # Number of live references.
+    def size
+      @objects.size
+    end
+
+    # Remove all references. Fires on_release for each.
+    def clear!
+      ids = @objects.keys.dup
+      ids.each { |id| release(id) }
+      @next_id = 1
+    end
+
+    # Check if an ID is registered.
+    def registered?(id)
+      @objects.key?(id)
+    end
+
+    # Thread-local singleton access
+    def self.current
+      Thread.current[:mana_object_registry] ||= new
+    end
+
+    def self.reset!
+      registry = Thread.current[:mana_object_registry]
+      registry&.clear!
+      Thread.current[:mana_object_registry] = nil
+    end
+  end
+end

data/lib/mana/remote_ref.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mana
+  # A proxy object representing a remote reference to an object in another engine.
+  #
+  # When JS or Python receives a complex Ruby object, they get a RemoteRef handle.
+  # Method calls on the proxy are routed back to the original object via the
+  # ObjectRegistry and the bidirectional calling channel.
+  #
+  # On the Ruby side, RemoteRef can also wrap foreign objects (JS/Python) that
+  # were passed to Ruby — method calls go through the engine's eval mechanism.
+  #
+  # GC behavior:
+  # - When a RemoteRef is garbage collected, its finalizer releases the entry
+  #   from the ObjectRegistry.
+  # - If an `on_release` callback is registered on the registry, it fires,
+  #   allowing the source engine to be notified (e.g., to free the foreign object).
+  class RemoteRef
+    attr_reader :ref_id, :source_engine, :type_name
+
+    def initialize(ref_id, source_engine:, type_name: nil, registry: nil)
+      @ref_id = ref_id
+      @source_engine = source_engine
+      @type_name = type_name
+      @registry = registry || ObjectRegistry.current
+      setup_release_callback
+    end
+
+    # Call a method on the remote object
+    def method_missing(name, *args, &block)
+      name_s = name.to_s
+
+      # Don't proxy Ruby internal methods
+      return super if %w[__id__ __send__ class is_a? kind_of? instance_of? respond_to? respond_to_missing? equal? nil? frozen? inspect to_s hash].include?(name_s)
+
+      obj = @registry.get(@ref_id)
+      raise Mana::Error, "Remote reference #{@ref_id} has been released" unless obj
+
+      obj.public_send(name, *args, &block)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      obj = @registry.get(@ref_id)
+      return false unless obj
+      obj.respond_to?(name, false)
+    end
+
+    # Explicitly release this reference
+    def release!
+      @registry.release(@ref_id)
+    end
+
+    # Check if the referenced object is still alive
+    def alive?
+      @registry.registered?(@ref_id)
+    end
+
+    def inspect
+      "#<Mana::RemoteRef id=#{@ref_id} engine=#{@source_engine} type=#{@type_name}>"
+    end
+
+    def to_s
+      obj = @registry.get(@ref_id)
+      obj ? obj.to_s : inspect
+    end
+
+    private
+
+    # Set up a release callback via Ruby finalizer.
+    # When this RemoteRef is garbage collected, the registry entry is released,
+    # which in turn fires any on_release callbacks (notifying the source engine).
+    # Uses a class method to avoid capturing `self` in the closure.
+    def setup_release_callback
+      release_proc = self.class.send(:release_callback, @ref_id, @registry)
+      ObjectSpace.define_finalizer(self, release_proc)
+    end
+
+    # Build a release proc that doesn't reference the RemoteRef instance.
+    # This avoids the "finalizer references object to be finalized" warning.
+    def self.release_callback(ref_id, registry)
+      proc { |_| registry.release(ref_id) }
+    end
+    private_class_method :release_callback
+  end
+end

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/mana.rb

@@ -11,6 +11,12 @@ require_relative "mana/namespace"
 require_relative "mana/memory_store"
 require_relative "mana/context_window"
 require_relative "mana/memory"
+require_relative "mana/object_registry"
+require_relative "mana/remote_ref"
+require_relative "mana/engines/base"
+require_relative "mana/engines/llm"
+require_relative "mana/engines/ruby_eval"
+require_relative "mana/engines/detect"
 require_relative "mana/engine"
 require_relative "mana/introspect"
 require_relative "mana/compiler"
@@ -44,8 +50,13 @@ module Mana
     def reset!
       @config = Config.new
       EffectRegistry.clear!
+      Engines.reset_detector!
+      ObjectRegistry.reset!
+      Engines::JavaScript.reset! if defined?(Engines::JavaScript)
+      Engines::Python.reset! if defined?(Engines::Python)
       Thread.current[:mana_memory] = nil
       Thread.current[:mana_mock] = nil
+      Thread.current[:mana_last_engine] = nil
     end
 
     # Define a custom effect that becomes an LLM tool

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: mini_racer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
 description: |
   Mana lets you write natural language strings in Ruby that execute via LLM
   with full access to your program's live state. Read/write variables, call
@@ -36,6 +50,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- data/lang-rules.yml
 - lib/mana.rb
 - lib/mana/backends/anthropic.rb
 - lib/mana/backends/base.rb
@@ -46,12 +61,20 @@ files:
 - lib/mana/context_window.rb
 - lib/mana/effect_registry.rb
 - lib/mana/engine.rb
+- lib/mana/engines/base.rb
+- lib/mana/engines/detect.rb
+- lib/mana/engines/javascript.rb
+- lib/mana/engines/llm.rb
+- lib/mana/engines/python.rb
+- lib/mana/engines/ruby_eval.rb
 - lib/mana/introspect.rb
 - lib/mana/memory.rb
 - lib/mana/memory_store.rb
 - lib/mana/mixin.rb
 - lib/mana/mock.rb
 - lib/mana/namespace.rb
+- lib/mana/object_registry.rb
+- lib/mana/remote_ref.rb
 - lib/mana/string_ext.rb
 - lib/mana/test.rb
 - lib/mana/version.rb