rubyx-py 0.1.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 310b31e267a6ba428456f3f2c27b7ab6efdb62b85643cb59e5fadbdd402faf58
+  data.tar.gz: 920b88249171d979b02461f6571b759c6b2048ba7a6e31805ffd69d10d7d973a
+SHA512:
+  metadata.gz: 9b4d8d5f9bb99d73908341a377d28c9cbf31be4d944f3bb93aa40f70aec525e720f3b85e1fc0d81b72321d846a0ee1ede27e603d6d54dfac74fe8447da9925e9
+  data.tar.gz: c8b593f701c843a543e87c447e8595f72f38f334e986b3be4845c0f05bba248b9cbecb337e38a39bafa74aef797c91f1563e9f3d4798a14fa1c28d21f96b0048

data/README.md

@@ -0,0 +1,469 @@
+<div align="center">
+
+# Rubyx-py
+
+**Call Python from Ruby. No microservices, no REST APIs, no serialization overhead.**
+
+Powered by Rust for safety and performance. Built for Rails.
+
+[![Gem Version](https://badge.fury.io/rb/rubyx.svg)](https://badge.fury.io/rb/rubyx)
+[![CI](https://github.com/yinho999/rubyx/actions/workflows/ci.yml/badge.svg)](https://github.com/yinho999/rubyx/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org)
+[![Rust](https://img.shields.io/badge/Rust-powered-orange.svg)](https://www.rust-lang.org)
+
+</div>
+
+---
+
+```ruby
+np = Rubyx.import('numpy')
+np.array([1, 2, 3]).mean().to_ruby # => 2.0
+```
+
+```ruby
+Rubyx.eval("sum(items)", items: [1, 2, 3, 4]) # => 10
+```
+
+```ruby
+# Stream LLM tokens in real-time
+Rubyx.stream(llm.generate("Tell me about Ruby")).each { |token| print token }
+```
+
+```ruby
+# Non-blocking — Ruby stays free while Python works
+future = Rubyx.async_await("model.predict(data)", data: [1, 2, 3])
+do_other_work()
+result = future.value # get result when ready
+```
+
+### Built with non-blocking in mind
+
+- **`Rubyx.stream`** / **`Rubyx.nb_stream`** — release Ruby's GVL during iteration, other threads and Fibers keep
+  running
+- **`Rubyx.async_await`** — spawns Python on background threads, returns a `Future` immediately
+- **`Rubyx.await`** — blocks only when you choose to
+
+Ideal for LLM streaming, ML inference, data pipelines, and high-concurrency Rails apps.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'rubyx-py'
+```
+
+Python is auto-managed by [uv](https://github.com/astral-sh/uv). No manual install needed.
+
+## Rails Setup Simple Example
+
+```bash
+rails generate rubyx:install
+```
+
+Creates `config/initializers/rubyx.rb`, `pyproject.toml`, and `app/python/`.
+
+### Configuration
+
+```ruby
+# config/initializers/rubyx.rb
+Rubyx::Rails.configure do |config|
+  config.pyproject_path = Rails.root.join('pyproject.toml')
+  config.auto_init = true
+  config.python_paths = [Rails.root.join('app/python').to_s]
+end
+```
+
+### Python dependencies
+
+```toml
+# pyproject.toml
+[project]
+name = "my-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = []
+```
+
+### 1. Sync — call a Python function
+
+```python
+# app/python/hello.py
+def greet(name):
+    return f"Hello, {name}!"
+```
+
+```ruby
+class GreetingsController < ApplicationController
+  def show
+    hello = Rubyx.import('hello')
+    render json: { message: hello.greet(params[:name]).to_ruby }
+  end
+end
+```
+
+### 2. Streaming — iterate a Python generator
+
+```python
+# app/python/count.py
+def count_up(n):
+    for i in range(n):
+        yield f"Step {i + 1}"
+```
+
+```ruby
+class CountController < ApplicationController
+  include ActionController::Live
+
+  def stream
+    response.headers['Content-Type'] = 'text/event-stream'
+
+    counter = Rubyx.import('count')
+    Rubyx.stream(counter.count_up(5)).each do |msg|
+      response.stream.write("data: #{msg}\n\n")
+    end
+  ensure
+    response.stream.close
+  end
+end
+```
+
+### 3. Async — non-blocking Python calls
+
+```python
+# app/python/tasks.py
+import asyncio
+
+
+async def delayed_greet(name, seconds=1):
+    await asyncio.sleep(seconds)
+    return f"Hello, {name}! (after {seconds}s)"
+```
+
+```ruby
+class TasksController < ApplicationController
+  def show
+    tasks = Rubyx.import('tasks')
+
+    # Non-blocking — returns a Future immediately
+    future = Rubyx.async_await(tasks.delayed_greet(params[:name], seconds: 2))
+    do_other_work()
+    render json: { message: future.value.to_ruby }
+  end
+end
+```
+
+## Rails Setup Advanced LLM Example
+
+```bash
+rails generate rubyx:install
+```
+
+Creates `config/initializers/rubyx.rb`, `pyproject.toml`, and `app/python/`.
+
+### Configuration
+
+```ruby
+# config/initializers/rubyx.rb
+Rubyx::Rails.configure do |config|
+  config.pyproject_path = Rails.root.join('pyproject.toml')
+  config.auto_init = true
+  config.python_paths = [Rails.root.join('app/python').to_s]
+end
+```
+
+### Python dependencies
+
+```toml
+# pyproject.toml
+[project]
+name = "my-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["numpy", "pandas", "transformers"]
+```
+
+### Write Python code
+
+```python
+# app/python/services/text_processing.py
+class TextAnalyzer:
+    def __init__(self, text):
+        self.text = text
+        self._words = text.split()
+
+    def summary(self):
+        return {
+            "word_count": len(self._words),
+            "unique_words": len(set(self._words)),
+            "avg_word_length": round(
+                sum(len(w) for w in self._words) / max(len(self._words), 1), 2
+            ),
+        }
+```
+
+### Call it from Rails
+
+```ruby
+
+class AnalysisController < ApplicationController
+  def analyze
+    tp = Rubyx.import('services.text_processing')
+    analyzer = tp.TextAnalyzer(params[:text])
+    render json: analyzer.summary.to_ruby
+  end
+end
+```
+
+### SSE streaming (LLM-style)
+
+```python
+# app/python/services/llm.py
+from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
+import threading
+
+_model, _tokenizer = None, None
+
+
+def load_model(name="Qwen/Qwen2.5-0.5B-Instruct"):
+    global _model, _tokenizer
+    _tokenizer = AutoTokenizer.from_pretrained(name)
+    _model = AutoModelForCausalLM.from_pretrained(name, torch_dtype="auto")
+
+
+def stream_generate(prompt, max_tokens=256):
+    messages = [{"role": "user", "content": prompt}]
+    text = _tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    inputs = _tokenizer([text], return_tensors="pt").to(_model.device)
+    streamer = TextIteratorStreamer(_tokenizer, skip_prompt=True, skip_special_tokens=True)
+
+    thread = threading.Thread(target=_model.generate,
+                              kwargs={**inputs, "max_new_tokens": max_tokens, "streamer": streamer})
+    thread.start()
+    for token in streamer:
+        if token:
+            yield token
+    thread.join()
+```
+
+```ruby
+# config/initializers/rubyx.rb
+Rubyx::Rails.configure do |config|
+  config.pyproject_path = Rails.root.join('pyproject.toml')
+  config.auto_init = true
+  config.python_paths = [Rails.root.join('app/python').to_s]
+end
+
+# Load models once at boot — must be inside after_initialize
+# so Python is already initialized by the Railtie
+Rails.application.config.after_initialize do
+  llm = Rubyx.import('services.llm')
+  llm.load_model("Qwen/Qwen2.5-0.5B-Instruct")
+end
+```
+
+```ruby
+class ChatController < ApplicationController
+  include ActionController::Live
+
+  def stream
+    llm = Rubyx.import('services.llm')
+    response.headers['Content-Type'] = 'text/event-stream'
+
+    Rubyx.stream(llm.stream_generate(params[:prompt])).each do |token|
+      token_str = token.to_s.gsub("\n", "\\n")
+      response.stream.write("data: #{token_str}\n\n")
+    end
+    response.stream.write("data: [DONE]\n\n")
+  ensure
+    response.stream.close
+  end
+end
+```
+
+### Rake tasks
+
+```bash
+rake rubyx:init         # Initialize Python environment
+rake rubyx:status       # Check environment status
+rake rubyx:packages     # List installed Python packages
+rake rubyx:clear_cache  # Clear cached environments
+```
+
+## Standalone Setup
+
+```ruby
+require 'rubyx'
+
+Rubyx.uv_init <<~TOML
+  [project]
+  name = "my-script"
+  version = "0.1.0"
+  requires-python = ">=3.12"
+  dependencies = ["numpy"]
+TOML
+
+np = Rubyx.import('numpy')
+np.array([1, 2, 3, 4, 5]).std().to_ruby # => 1.4142135623730951
+```
+
+## Eval with Globals
+
+Pass Ruby data directly into Python:
+
+```ruby
+Rubyx.eval("x ** 2 + y ** 2", x: 3, y: 4).to_ruby # => 25
+Rubyx.eval("f'Hello, {name}!'", name: "World").to_ruby # => "Hello, World!"
+Rubyx.eval("max(items)", items: [3, 1, 4, 1, 5]).to_ruby # => 5
+```
+
+Supports: Integer, Float, String, Symbol, Bool, nil, Array, Hash, and RubyxObject.
+
+## Python Objects
+
+Python objects are wrapped as `RubyxObject`:
+
+```ruby
+os = Rubyx.import('os')
+os.getcwd().to_ruby # => "/home/user"
+os.path.exists("/tmp").to_ruby # => true
+
+# Subscript access
+d = Rubyx.eval("{'a': 1, 'b': 2}")
+d['a'].to_ruby # => 1
+d['c'] = 3
+
+# Enumerable
+py_list = Rubyx.eval("[1, 2, 3, 4, 5]")
+py_list.map { |x| x.to_ruby * 2 } # => [2, 4, 6, 8, 10]
+py_list.select { |x| x.to_ruby > 3 } # filtered RubyxObjects
+
+# Introspection
+py_list.truthy? # => true
+py_list.callable? # => false
+py_list.py_type # => "list"
+```
+
+## Context
+
+Persistent state across multiple eval calls:
+
+```ruby
+ctx = Rubyx.context
+
+ctx.eval("import math")
+ctx.eval("data = [1, 2, 3, 4, 5]")
+ctx.eval("avg = sum(data) / len(data)")
+ctx.eval("avg").to_ruby # => 3.0
+
+# Inject Ruby data into context
+ctx.eval("total = base + offset", base: 100, offset: 42)
+ctx.eval("total").to_ruby # => 142
+```
+
+## Streaming
+
+```ruby
+gen = Rubyx.eval("(x ** 2 for x in range(5))")
+Rubyx.stream(gen).each { |val| puts val } # 0, 1, 4, 9, 16
+
+# Non-blocking (releases GVL for other Ruby threads)
+Rubyx.nb_stream(gen).each { |val| process(val) }
+```
+
+## Async / Await
+
+```ruby
+ctx = Rubyx.context
+ctx.eval("import asyncio")
+ctx.eval("async def fetch(url): ...")
+
+# Blocking
+result = ctx.await("fetch(url)", url: "https://example.com")
+
+# Non-blocking (returns Future)
+future = ctx.async_await("fetch(url)", url: "https://example.com")
+do_other_stuff()
+result = future.value # blocks only when needed
+future.ready? # check without blocking
+```
+
+## Error Handling
+
+Python exceptions map to Ruby classes:
+
+```ruby
+
+begin
+  Rubyx.eval('{}["missing"]')
+rescue Rubyx::KeyError => e
+  puts e.message # includes Python traceback
+end
+```
+
+| Python                                | Ruby                          |
+|---------------------------------------|-------------------------------|
+| `KeyError`                            | `Rubyx::KeyError`             |
+| `IndexError`                          | `Rubyx::IndexError`           |
+| `ValueError`                          | `Rubyx::ValueError`           |
+| `TypeError`                           | `Rubyx::TypeError`            |
+| `AttributeError`                      | `Rubyx::AttributeError`       |
+| `ImportError` / `ModuleNotFoundError` | `Rubyx::ImportError`          |
+| `SyntaxError`                         | `SyntaxError` (Ruby built-in) |
+| Everything else                       | `Rubyx::PythonError`          |
+
+All inherit from `Rubyx::Error` (`StandardError`).
+
+## Local Python Files
+
+```python
+# app/python/services/analyzer.py
+class Analyzer:
+    def __init__(self, data):
+        self.data = data
+
+    def summary(self):
+        return {"count": len(self.data), "sum": sum(self.data)}
+```
+
+```ruby
+svc = Rubyx.import('services.analyzer')
+svc.Analyzer([1, 2, 3]).summary.to_ruby # => {"count" => 3, "sum" => 6}
+```
+
+## API Reference
+
+| Method                               | Description                     |
+|--------------------------------------|---------------------------------|
+| `Rubyx.uv_init(toml, **opts)`        | Setup Python env and initialize |
+| `Rubyx.import(name)`                 | Import a Python module          |
+| `Rubyx.eval(code, **globals)`        | Evaluate Python code            |
+| `Rubyx.await(code, **globals)`       | Run async code (blocking)       |
+| `Rubyx.async_await(code, **globals)` | Run async code (returns Future) |
+| `Rubyx.stream(iterable)`             | Stream a Python generator       |
+| `Rubyx.nb_stream(iterable)`          | Non-blocking stream (GVL-aware) |
+| `Rubyx.context`                      | Create isolated Python context  |
+| `Rubyx.initialized?`                 | Check if Python is ready        |
+
+| RubyxObject              |                               |
+|--------------------------|-------------------------------|
+| `.to_ruby`               | Convert to native Ruby type   |
+| `.to_s` / `.inspect`     | String / repr                 |
+| `.method_missing`        | Delegates to Python           |
+| `[]` / `[]=` / `.delete` | Subscript access              |
+| `.each`                  | Iterate (includes Enumerable) |
+| `.truthy?` / `.falsy?`   | Python truthiness             |
+| `.callable?`             | Check if callable             |
+| `.py_type`               | Python type name              |
+
+## Requirements
+
+- Ruby >= 3.0
+- Rust (for building from source)
+- Python >= 3.12 (auto-managed by uv)
+
+Precompiled gems available for Linux and macOS (x86_64 and ARM64).
+
+## License
+
+MIT

data/ext/rubyx/src/python/sync_adapter.py

@@ -0,0 +1,31 @@
+import asyncio
+from asyncio import AbstractEventLoop
+from typing import AsyncGenerator
+
+
+class AsyncToSync:
+    def __init__(self, async_gen: AsyncGenerator):
+        self._agen = async_gen
+        self._loop: AbstractEventLoop = asyncio.new_event_loop()
+
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            coro = self._agen.__anext__()
+            return self._loop.run_until_complete(coro)
+        except StopAsyncIteration:
+            self._loop.close()
+            raise StopIteration
+        except BaseException:
+            self._loop.close()
+            raise
+
+    def close(self):
+        try:
+            self._loop.run_until_complete(self._agen.aclose())
+        except Exception:
+            pass
+        self._loop.close()

data/lib/generators/rubyx/install_generator.rb

@@ -0,0 +1,24 @@
+module Rubyx
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_pyproject
+        copy_file 'pyproject.toml', 'pyproject.toml'
+      end
+
+      def create_initializer
+        copy_file 'rubyx_initializer.rb', 'config/initializers/rubyx.rb'
+      end
+
+      def create_python_directory
+        empty_directory 'app/python'
+        copy_file 'example.py', 'app/python/example.py'
+      end
+
+      def add_gitignore
+        append_to_file '.gitignore', "\n# Python (managed by rubyx-py)\n.venv/\n" if File.exist?('.gitignore')
+      end
+    end
+  end
+end

data/lib/generators/rubyx/templates/rubyx_initializer.rb

@@ -0,0 +1,17 @@
+Rubyx::Rails.configure do |config|
+  # Path to your Python project's pyproject.toml
+  config.pyproject_path = Rails.root.join('pyproject.toml')
+
+  # Auto-initialize Python when Rails boots
+  # Set to false for forking servers (Puma workers) — use on_worker_boot instead
+  config.auto_init = true
+
+  # Directories to add to Python's sys.path (makes .py files importable)
+  config.python_paths = [Rails.root.join('app/python').to_s]
+
+  # Use system uv instead of auto-downloading (optional)
+  # config.uv_path = `which uv`.strip
+
+  # Extra arguments for uv sync (optional)
+  # config.uv_args = ['--extra', 'ml']
+end

data/lib/rubyx/context.rb

@@ -0,0 +1,27 @@
+module Rubyx
+  class Context
+    def eval(code, **globals)
+      if globals.empty?
+        _eval(code.to_s)
+      else
+        _eval_with_globals(code.to_s, globals)
+      end
+    end
+
+    def await(code, **globals)
+      if globals.empty?
+        _await(code.to_s)
+      else
+        _await_with_globals(code.to_s, globals)
+      end
+    end
+
+    def async_await(code, **globals)
+      if globals.empty?
+        _async_await(code.to_s)
+      else
+        _async_await_with_globals(code.to_s, globals)
+      end
+    end
+  end
+end

data/lib/rubyx/error.rb

@@ -0,0 +1,30 @@
+module Rubyx
+  VALID_MODULE_NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*\z/
+
+  class Error < StandardError; end
+
+  class PythonError < Error; end
+
+  class ImportError < PythonError; end
+
+  class InvalidModuleNameError < Error; end
+
+  class KeyError < Error; end
+
+  class IndexError < Error; end
+
+  class ValueError < Error; end
+
+  class AttributeError < Error; end
+
+  class TypeError < Error; end
+
+  module Uv
+    class Error < Rubyx::Error; end
+
+    class SetupError < Error; end
+
+    class InitError < Error; end
+  end
+
+end

data/lib/rubyx/rails.rb

@@ -0,0 +1,105 @@
+module Rubyx
+  module Rails
+    class Error < Rubyx::Error; end
+
+    class Configuration
+      attr_accessor :pyproject_path, :pyproject_content, :auto_init,
+                    :force_reinit, :uv_version, :debug, :python_paths,
+                    :uv_path, :uv_args
+
+      def initialize
+        @pyproject_path = nil
+        @pyproject_content = nil
+        @auto_init = false
+        @force_reinit = false
+        @uv_version = Rubyx::Uv::DEFAULT_UV_VERSION
+        @debug = false
+        @python_paths = []
+        @uv_path = nil
+        @uv_args = []
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      def init!
+        return if initialized?
+
+        config = configuration
+
+        pyproject_toml = resolve_pyproject(config)
+        project_dir = resolve_project_dir(config)
+
+        options = {
+          force: config.force_reinit,
+          uv_version: config.uv_version,
+          project_dir: project_dir,
+          uv_args: config.uv_args,
+        }
+        options[:uv_path] = config.uv_path if config.uv_path
+
+        Rubyx.uv_init(pyproject_toml, **options)
+
+        inject_python_paths(config.python_paths)
+
+        @initialized = true
+
+        if config.debug
+          ::Rails.logger.info "[Rubyx] Python initialized (project_dir: #{project_dir})"
+        end
+      rescue => e
+        @initialized = false
+        ::Rails.logger.error "[Rubyx] Failed to initialize Python: #{e.message}" if defined?(::Rails.logger)
+        raise
+      end
+
+      def ensure_initialized!
+        return if initialized?
+
+        init!
+      end
+
+      def initialized?
+        @initialized == true
+      end
+
+      private
+
+      def resolve_pyproject(config)
+        if config.pyproject_path && File.exist?(config.pyproject_path.to_s)
+          File.read(config.pyproject_path.to_s)
+        elsif config.pyproject_content
+          config.pyproject_content
+        else
+          raise Error, "No pyproject.toml configured. Set pyproject_path or pyproject_content in config/initializers/rubyx.rb"
+        end
+      end
+
+      def resolve_project_dir(config)
+        if config.pyproject_path
+          File.dirname(config.pyproject_path.to_s)
+        elsif defined?(::Rails) && ::Rails.respond_to?(:root)
+          ::Rails.root.to_s
+        else
+          Dir.pwd
+        end
+      end
+
+      def inject_python_paths(paths)
+        return if paths.nil? || paths.empty?
+
+        paths.each do |path|
+          expanded = File.expand_path(path)
+          Rubyx.eval("import sys; sys.path.insert(0, '#{expanded}')") if Dir.exist?(expanded)
+        end
+      end
+    end
+  end
+end

data/lib/rubyx/railtie.rb

@@ -0,0 +1,20 @@
+require_relative 'rails'
+
+module Rubyx
+  class Railtie < ::Rails::Railtie
+    config.rubyx = ActiveSupport::OrderedOptions.new
+
+    # Auto-initialize Python after all config initializers have run
+    config.after_initialize do
+      if Rubyx::Rails.configuration.auto_init
+        Rubyx::Rails.init!
+        ::Rails.logger.info '[Rubyx] Python environment initialized successfully'
+      end
+    end
+
+    # Register rake tasks
+    rake_tasks do
+      load 'rubyx/tasks/rubyx.rake'
+    end
+  end
+end

data/lib/rubyx/uv.rb

@@ -0,0 +1,261 @@
+require 'digest'
+require 'fileutils'
+require 'open-uri'
+require 'stringio'
+require 'rubygems/package'
+require 'zlib'
+
+module Rubyx
+  module Uv
+    DEFAULT_UV_VERSION = '0.10.2'.freeze
+
+    class << self
+      # Download uv (if needed), write pyproject.toml, and run `uv sync`.
+      #
+      # @param pyproject_toml [String] Content of pyproject.toml
+      # @param force [Boolean] Force re-setup even if .venv exists
+      # @param uv_version [String] Version of uv to download
+      # @param project_dir [String, Symbol, nil] Where to create the project
+      #   - nil: use Dir.pwd
+      #   - :cache: use a hash-based cache directory
+      #   - String: use the specified path
+      # @param uv_args [Array<String>] Extra arguments to pass to `uv sync`
+      # @param uv_path [String, nil] Path to an existing uv binary. When set,
+      #   auto-download is skipped entirely.
+      # @return [String] The resolved project directory path
+      def setup(pyproject_toml, force: false, uv_version: DEFAULT_UV_VERSION,
+                project_dir: nil, uv_args: [], uv_path: nil)
+        proj_dir = resolve_project_dir(pyproject_toml, uv_version, project_dir)
+
+        venv_dir = File.join(proj_dir, '.venv')
+        pyproject_path = File.join(proj_dir, 'pyproject.toml')
+
+        needs_setup = force || !Dir.exist?(venv_dir)
+
+        if !needs_setup && File.exist?(pyproject_path)
+          needs_setup = File.read(pyproject_path).strip != pyproject_toml.strip
+        end
+
+        if needs_setup
+          FileUtils.rm_rf(venv_dir) if force
+          FileUtils.mkdir_p(proj_dir)
+          File.write(pyproject_path, pyproject_toml)
+
+          success = run_uv!(
+            ['sync', '--managed-python', '--no-config', '--project', proj_dir, *uv_args],
+            chdir: proj_dir,
+            env: { 'UV_PYTHON_INSTALL_DIR' => python_install_dir(uv_version) },
+            uv_version: uv_version,
+            uv_path: uv_path
+          )
+
+          unless success
+            FileUtils.rm_rf(venv_dir)
+            raise SetupError, 'uv sync failed to setup Python environment'
+          end
+        end
+
+        proj_dir
+      end
+
+      # Parse pyvenv.cfg, resolve platform paths, and call Rubyx.init.
+      #
+      # @param pyproject_toml [String] Content of pyproject.toml (used to resolve project_dir)
+      # @param uv_version [String] Version of uv (used to resolve project_dir)
+      # @param project_dir [String, Symbol, nil] Same as setup
+      # @return [Hash] Resolved paths (:root_dir, :project_dir, :python_dl, etc.)
+      def init(pyproject_toml, uv_version: DEFAULT_UV_VERSION, project_dir: nil)
+        proj_dir = resolve_project_dir(pyproject_toml, uv_version, project_dir)
+
+        venv_dir = File.join(proj_dir, '.venv')
+        raise InitError, "Not set up. Call Rubyx::Uv.setup first." unless Dir.exist?(venv_dir)
+
+        cfg_path = File.join(venv_dir, 'pyvenv.cfg')
+        raise InitError, "pyvenv.cfg not found at #{cfg_path}" unless File.exist?(cfg_path)
+
+        pyvenv_cfg = File.read(cfg_path)
+        home_line = pyvenv_cfg.lines.find { |l| l.start_with?('home = ') }
+        raise InitError, "Could not find 'home' in pyvenv.cfg" unless home_line
+
+        home_path = home_line.sub('home = ', '').strip
+        root_dir = File.dirname(home_path) # Parent of bin/
+
+        paths = platform_paths(root_dir, proj_dir)
+        validate_paths!(paths)
+
+        sys_paths = []
+        sys_paths << paths[:venv_packages] if paths[:venv_packages]
+        sys_paths << proj_dir if project_dir && project_dir != :cache
+
+        # Call the Rust init
+        Rubyx.init(
+          paths[:python_dl],
+          paths[:python_home],
+          paths[:python_exe],
+          sys_paths
+        )
+
+        { root_dir: root_dir, project_dir: proj_dir, **paths }
+      end
+
+      private
+
+      # Download the uv binary from GitHub releases.
+      def download_uv!(uv_version)
+        archive_type, archive_name = archive_name_for_platform
+        url = "https://github.com/astral-sh/uv/releases/download/#{uv_version}/#{archive_name}"
+
+        warn "Downloading uv #{uv_version}..."
+
+        archive_data = URI.open(url, 'rb', &:read)
+        uv_binary = extract_uv(archive_type, archive_data)
+
+        path = default_uv_path(uv_version)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, uv_binary)
+        File.chmod(0o755, path)
+
+        path
+      end
+
+      def archive_name_for_platform
+        case RUBY_PLATFORM
+        when /arm64.*darwin/, /aarch64.*darwin/
+          [:tar_gz, 'uv-aarch64-apple-darwin.tar.gz']
+        when /x86_64.*darwin/, /darwin/
+          [:tar_gz, 'uv-x86_64-apple-darwin.tar.gz']
+        when /aarch64.*linux/
+          [:tar_gz, 'uv-aarch64-unknown-linux-gnu.tar.gz']
+        when /x86_64.*linux/, /linux/
+          [:tar_gz, 'uv-x86_64-unknown-linux-gnu.tar.gz']
+        when /mingw/, /mswin/, /cygwin/
+          [:zip, 'uv-x86_64-pc-windows-msvc.zip']
+        else
+          raise SetupError, "Unsupported platform: #{RUBY_PLATFORM}"
+        end
+      end
+
+      def extract_uv(type, data)
+        case type
+        when :tar_gz
+          io = StringIO.new(data)
+          gzip = Zlib::GzipReader.new(io)
+          Gem::Package::TarReader.new(gzip) do |tar|
+            tar.each do |entry|
+              return entry.read if File.basename(entry.full_name) == 'uv'
+            end
+          end
+          raise SetupError, 'uv binary not found in archive'
+        when :zip
+          require 'zip'
+          Zip::File.open_buffer(data) do |zip|
+            zip.each do |entry|
+              return entry.get_input_stream.read if File.basename(entry.name, '.*') == 'uv'
+            end
+          end
+          raise SetupError, 'uv binary not found in archive'
+        end
+      end
+
+      # Run a uv command.
+      #
+      # @param uv_path [String, nil] Custom uv binary path. When nil, uses
+      #   the auto-downloaded binary (downloading if needed).
+      def run_uv!(args, chdir:, env:, uv_version:, uv_path: nil)
+        path = if uv_path
+                 raise SetupError, "uv not found at #{uv_path}" unless File.exist?(uv_path)
+                 uv_path
+               else
+                 default = default_uv_path(uv_version)
+                 download_uv!(uv_version) unless File.exist?(default)
+                 default
+               end
+
+        require 'open3'
+        full_env = env.transform_keys(&:to_s)
+        success = nil
+        Dir.chdir(chdir) do
+          Open3.popen2e(full_env, path, *args) do |stdin, stdout_err, wait_thr|
+            stdin.close
+            stdout_err.each_line { |line| $stderr.print line }
+            success = wait_thr.value.success?
+          end
+        end
+
+        success
+      end
+
+      # Resolve platform-specific paths for libpython, home, exe, and site-packages.
+      def platform_paths(root_dir, project_dir)
+        case RUBY_PLATFORM
+        when /darwin/
+          {
+            python_dl: find_lib(root_dir, 'lib/libpython3.*.dylib'),
+            python_home: root_dir,
+            python_exe: File.join(project_dir, '.venv/bin/python'),
+            venv_packages: find_lib(project_dir, '.venv/lib/python3.*/site-packages'),
+          }
+        when /linux/
+          {
+            python_dl: find_lib(root_dir, 'lib/libpython3.*.so'),
+            python_home: root_dir,
+            python_exe: File.join(project_dir, '.venv/bin/python'),
+            venv_packages: find_lib(project_dir, '.venv/lib/python3.*/site-packages'),
+          }
+        when /mingw/, /mswin/, /cygwin/
+          {
+            python_dl: find_lib(root_dir, 'python3*.dll'),
+            python_home: root_dir,
+            python_exe: File.join(project_dir, '.venv/Scripts/python.exe'),
+            venv_packages: File.join(project_dir, '.venv/Lib/site-packages'),
+          }
+        else
+          raise InitError, "Unsupported platform: #{RUBY_PLATFORM}"
+        end
+      end
+
+      def find_lib(base_dir, pattern)
+        matches = Dir.glob(File.join(base_dir, pattern))
+        matches.min_by(&:length)
+      end
+
+      def validate_paths!(paths)
+        paths.each do |key, path|
+          next if path.nil? && key == :venv_packages
+          raise InitError, "Path not found: #{key} (#{path})" unless path && File.exist?(path)
+        end
+      end
+
+      # Determine where the project directory should be.
+      def resolve_project_dir(pyproject_toml, uv_version, project_dir)
+        case project_dir
+        when nil
+          Dir.pwd
+        when :cache
+          cache_id = Digest::MD5.hexdigest(pyproject_toml)
+          File.join(cache_dir(uv_version), 'projects', cache_id)
+        else
+          File.expand_path(project_dir)
+        end
+      end
+
+      # Path to the auto-downloaded uv binary.
+      def default_uv_path(uv_version)
+        File.join(cache_dir(uv_version), 'bin', 'uv')
+      end
+
+      # Root cache directory for this rubyx + uv version combination.
+      def cache_dir(uv_version)
+        File.join(
+          ENV.fetch('XDG_CACHE_HOME', File.join(Dir.home, '.cache')),
+          'rubyx', Rubyx::VERSION, 'uv', uv_version
+        )
+      end
+
+      # Directory where uv installs managed Python distributions.
+      def python_install_dir(uv_version)
+        File.join(cache_dir(uv_version), 'python')
+      end
+    end
+  end
+end

data/lib/rubyx/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Rubyx
+  VERSION = "0.1.0".freeze
+end

data/lib/rubyx-py.rb

@@ -0,0 +1 @@
+require_relative 'rubyx'

data/lib/rubyx.rb

@@ -0,0 +1,136 @@
+require 'rbconfig'
+require_relative 'rubyx/version'
+require_relative 'rubyx/error'
+
+# Load the native extension
+begin
+  ruby_version = RUBY_VERSION.match(/\d+\.\d+/)[0]
+  require "rubyx/#{ruby_version}/rubyx"
+rescue LoadError
+  begin
+    require 'rubyx/rubyx'
+  rescue LoadError
+    # dev
+    dev_root = File.expand_path('..', __dir__)
+    unless File.exist?(File.join(dev_root, 'Cargo.toml'))
+      raise LoadError,
+            "Could not load rubyx native extension. Install the rubyx-py gem."
+    end
+
+    lib_ext = case RbConfig::CONFIG['host_os']
+              when /darwin/ then 'dylib'
+              when /linux/ then 'so'
+              when /mingw|mswin/ then 'dll'
+              else 'so'
+              end
+    bundle_ext = RbConfig::CONFIG['host_os'] =~ /darwin/ ? 'bundle' : lib_ext
+
+    lib_path = File.join(dev_root, "target/release/librubyx.#{lib_ext}")
+    bundle_path = File.join(dev_root, "target/release/rubyx.#{bundle_ext}")
+
+    unless File.exist?(lib_path)
+      raise LoadError,
+            "Native extension not built. Run: cargo build --release"
+    end
+
+    if !File.exist?(bundle_path) || File.mtime(lib_path) > File.mtime(bundle_path)
+      require 'fileutils'
+      FileUtils.cp(lib_path, bundle_path)
+    end
+    require bundle_path
+  end
+end
+
+require_relative 'rubyx/context'
+require_relative 'rubyx/uv'
+require_relative 'rubyx/railtie' if defined?(::Rails::Railtie)
+
+module Rubyx
+  # Import a Python module by name.
+  #
+  # @param module_name [String] Python module name (e.g., "os", "numpy", "my_module.sub")
+  # @return [RubyxObject] Wrapped Python module
+  # @raise [InvalidModuleNameError] if the name contains invalid characters
+  def self.import(module_name)
+    name = module_name.to_s
+    unless name.match?(VALID_MODULE_NAME_PATTERN)
+      raise InvalidModuleNameError,
+            "Invalid Python module name: '#{name}'. " \
+              "Module names must contain only alphanumeric characters, underscores, and dots."
+    end
+    _import(name)
+  end
+
+  # Evaluate Python code and return the result.
+  #
+  # @param code [String] Python code to evaluate
+  # @param globals [Hash] Ruby values to inject as Python globals
+  # @return [RubyxObject] The result as a wrapped Python object
+  # @example
+  #   Rubyx.eval("x + y", x: 10, y: 20)
+  class << self
+    public define_method(:eval) { |code, **globals|
+      if globals.empty?
+        Rubyx._eval(code.to_s)
+      else
+        Rubyx._eval_with_globals(code.to_s, globals)
+      end
+    }
+  end
+
+  # Run a Python coroutine with asyncio.run() (blocking).
+  # Accepts either a RubyxObject (coroutine) or a code string with globals.
+  #
+  # @param code_or_coroutine [String, RubyxObject] Python code or coroutine object
+  # @param globals [Hash] Ruby values to inject as Python globals (only with code string)
+  # @return [RubyxObject] The awaited result
+  # @example
+  #   Rubyx.await("fetch(url)", url: "https://example.com")
+  def self.await(code_or_coroutine, **globals)
+    if code_or_coroutine.is_a?(String)
+      if globals.empty?
+        _await_with_globals(code_or_coroutine, {})
+      else
+        _await_with_globals(code_or_coroutine, globals)
+      end
+    else
+      raise ArgumentError, "cannot pass globals with a coroutine object" unless globals.empty?
+      _await(code_or_coroutine)
+    end
+  end
+
+  # Run a Python coroutine on a background thread (non-blocking).
+  # Accepts either a RubyxObject (coroutine) or a code string with globals.
+  #
+  # @param code_or_coroutine [String, RubyxObject] Python code or coroutine object
+  # @param globals [Hash] Ruby values to inject as Python globals (only with code string)
+  # @return [Rubyx::Future] A future that resolves to the result
+  # @example
+  #   future = Rubyx.async_await("fetch(url)", url: "https://example.com")
+  #   future.value
+  def self.async_await(code_or_coroutine, **globals)
+    if code_or_coroutine.is_a?(String)
+      if globals.empty?
+        _async_await_with_globals(code_or_coroutine, {})
+      else
+        _async_await_with_globals(code_or_coroutine, globals)
+      end
+    else
+      raise ArgumentError, "cannot pass globals with a coroutine object" unless globals.empty?
+      _async_await(code_or_coroutine)
+    end
+  end
+
+  # Convenience method: setup Python environment via uv and initialize.
+  #
+  # @param pyproject_toml [String] Content of pyproject.toml
+  # @param options [Hash] Options passed to Uv.setup and Uv.init
+  # @return [Hash] Resolved paths from Uv.init
+  def self.uv_init(pyproject_toml, **options)
+    setup_keys = %i[force uv_version project_dir uv_args uv_path]
+    init_keys = %i[uv_version project_dir]
+
+    Uv.setup(pyproject_toml, **options.slice(*setup_keys))
+    Uv.init(pyproject_toml, **options.slice(*init_keys))
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: rubyx-py
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: aarch64-linux
+authors:
+- Naiker
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Call Python libraries directly from Ruby and Rails. No microservices,
+  no REST APIs — just seamless interop. Powered by Rust for safety and performance.
+email:
+- yinho999@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- ext/rubyx/src/python/sync_adapter.py
+- lib/generators/rubyx/install_generator.rb
+- lib/generators/rubyx/templates/rubyx_initializer.rb
+- lib/rubyx-py.rb
+- lib/rubyx.rb
+- lib/rubyx/3.1/rubyx.so
+- lib/rubyx/3.2/rubyx.so
+- lib/rubyx/3.3/rubyx.so
+- lib/rubyx/3.4/rubyx.so
+- lib/rubyx/context.rb
+- lib/rubyx/error.rb
+- lib/rubyx/rails.rb
+- lib/rubyx/railtie.rb
+- lib/rubyx/uv.rb
+- lib/rubyx/version.rb
+homepage: https://github.com/yinho999/rubyx
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yinho999/rubyx
+  source_code_uri: https://github.com/yinho999/rubyx
+  changelog_uri: https://github.com/yinho999/rubyx/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yinho999/rubyx/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby-Python bridge powered by Rust
+test_files: []